Universal Object Model (UOM)

The Universal Object Model is the standardized schema that defines how simulations are structured in the UAW system. This document describes the current implementation, including both legacy compatibility features and modern extensible patterns.

Overview¶

The UOM provides a flexible foundation for modeling any real-world process by defining objects, their properties, and how tasks interact with those objects. The model supports both traditional manufacturing processes and modern digital-physical hybrid workflows.

Core Principles¶

1. Flexible Object Typing¶

The system supports standard object types (actor, equipment, resource, product) as well as custom types for specialized domains (digital_object, display, screen_element, vehicle, etc.).

2. Property-Based Configuration¶

All object behavior is defined through properties, allowing for unlimited customization without changing the core schema.

3. Interaction-Driven Dynamics¶

Tasks modify object properties through a rich interaction system, enabling complex state changes and realistic process modeling.

Schema Structure¶

{
  "simulation": {
    "meta": { ... },
    "config": { ... },
    "layout": { ... },
    "objects": [ ... ],
    "tasks": [ ... ],
    "production_recipes": { ... }
  }
}

Meta Section¶

Contains descriptive information about the simulation:

{
  "meta": {
    "title": "Bread Production Process",
    "description": "Complete bakery production workflow",
    "version": "2.1",
    "created_date": "2024-09-13",
    "author": "Process Engineer",
    "industry": "Food Manufacturing",
    "complexity_level": "intermediate"
  }
}

Config Section¶

Defines timing and simulation parameters:

{
  "config": {
    "time_unit": "minutes",
    "start_time": "06:00",
    "end_time": "18:00",
    "time_step": 1,
    "currency": "USD",
    "locale": "en-US"
  }
}

Layout Section¶

Defines physical and digital spaces:

{
  "layout": {
    "areas": {
      "prep_area": {
        "name": "Preparation Area",
        "type": "physical",
        "coordinates": { "x": 0, "y": 0, "width": 10, "height": 5 }
      },
      "virtual_control_room": {
        "name": "Digital Control Center",
        "type": "digital",
        "coordinates": { "x": 0, "y": 0, "z": 0 },
        "bounds": { "width": 20, "height": 10, "depth": 15 }
      }
    }
  }
}

Object Types¶

Standard Object Types¶

Actor¶

Represents people or autonomous agents that perform tasks:

{
  "id": "head_baker",
  "type": "actor",
  "name": "Head Baker",
  "emoji": "👨‍🍳",
  "properties": {
    "role": "Senior Baker",
    "skill_level": "expert",
    "cost_per_hour": 28.50,
    "location": "prep_area",
    "certifications": ["food_safety", "artisan_bread"],
    "shift_start": "06:00",
    "shift_end": "14:00"
  }
}

Standard Properties: - role: Job title or function - skill_level: Proficiency level (beginner, intermediate, advanced, expert) - cost_per_hour: Labor cost for economic analysis - location: Current physical location - shift_start/shift_end: Working hours

Equipment¶

Physical tools, machinery, and apparatus:

{
  "id": "industrial_mixer",
  "type": "equipment",
  "name": "Industrial Dough Mixer",
  "emoji": "⚙️",
  "properties": {
    "state": "clean",
    "capacity": 50,
    "capacity_unit": "kg",
    "power_rating": 5.5,
    "power_unit": "kW",
    "location": "prep_area",
    "maintenance_hours": 2000,
    "last_maintenance": "2024-09-01"
  }
}

Standard Properties: - state: Current operational state (clean, dirty, in_use, maintenance, broken) - capacity: Maximum throughput or volume - power_rating: Energy consumption - location: Physical position - maintenance_hours: Hours until next maintenance

Resource¶

Consumable materials and supplies:

{
  "id": "organic_flour",
  "type": "resource",
  "name": "Organic Bread Flour",
  "emoji": "🌾",
  "properties": {
    "quantity": 500,
    "unit": "kg",
    "cost_per_unit": 0.85,
    "supplier": "Local Grain Mill",
    "expiration_date": "2024-12-15",
    "location": "dry_storage",
    "batch_number": "FL-2024-089",
    "quality_grade": "premium"
  }
}

Standard Properties: - quantity: Current amount available - unit: Measurement unit (kg, L, pieces, etc.) - cost_per_unit: Material cost for economic analysis - expiration_date: Shelf life tracking - location: Storage location

Product¶

Items created during the process:

{
  "id": "artisan_sourdough",
  "type": "product",
  "name": "Artisan Sourdough Loaf",
  "emoji": "🍞",
  "properties": {
    "quantity": 0,
    "unit": "loaves",
    "revenue_per_unit": 8.50,
    "production_time": 240,
    "shelf_life_days": 3,
    "location": "cooling_area",
    "weight_per_unit": 0.8,
    "quality_standards": "artisan_grade"
  }
}

Standard Properties: - quantity: Current inventory level - revenue_per_unit: Selling price for economic analysis - production_time: Time required to produce one unit - shelf_life_days: Product freshness period

Digital Object Types¶

Digital Location¶

Virtual spaces within digital systems:

{
  "id": "warehouse_sim",
  "type": "digital_location",
  "name": "Virtual Warehouse Environment",
  "properties": {
    "environment_type": "logistics_simulation",
    "coordinate_system": "cartesian_3d",
    "bounds": {
      "x": { "min": -100, "max": 100 },
      "y": { "min": 0, "max": 30 },
      "z": { "min": -100, "max": 100 }
    },
    "physics_enabled": true,
    "lighting_model": "realistic",
    "collision_detection": true,
    "gravity": 9.81
  }
}

Digital Object¶

Virtual items within digital spaces:

{
  "id": "autonomous_forklift",
  "type": "digital_object",
  "name": "AI-Powered Forklift",
  "properties": {
    "digital_type": "autonomous_vehicle",
    "position": { "x": 0, "y": 0, "z": 0 },
    "rotation": { "x": 0, "y": 0, "z": 0 },
    "scale": { "x": 1, "y": 1, "z": 1 },
    "movement_speed": 3.5,
    "load_capacity": 2000,
    "battery_level": 85,
    "digital_location": "warehouse_sim"
  }
}

Display¶

Screens and digital interfaces:

{
  "id": "production_dashboard",
  "type": "display",
  "name": "Production Control Dashboard",
  "emoji": "📊",
  "properties": {
    "display_type": "control_interface",
    "resolution": { "width": 2560, "height": 1440 },
    "viewport": { "x": 0, "y": 0, "width": 2560, "height": 1440 },
    "location": "control_room",
    "active": true,
    "brightness": 75,
    "refresh_rate": 120,
    "touch_enabled": true
  }
}

Screen Element¶

Interactive components within displays:

{
  "id": "efficiency_display",
  "type": "screen_element",
  "name": "Production Efficiency Display",
  "properties": {
    "element_type": "label",
    "display_id": "production_dashboard",
    "position": { "x": 200, "y": 300 },
    "dimensions": { "width": 250, "height": 30 },
    "text": "Efficiency: 87.5%",
    "font_size": 16,
    "color": "green",
    "visible": true,
    "interactive": false
  }
}

Custom Object Types¶

The system supports unlimited custom object types for specialized domains:

Vehicle Example¶

{
  "id": "delivery_truck_01",
  "type": "vehicle",
  "name": "Delivery Truck #1",
  "emoji": "🚛",
  "properties": {
    "vehicle_type": "box_truck",
    "fuel_level": 0.75,
    "fuel_capacity": 120,
    "fuel_unit": "liters",
    "max_payload": 3500,
    "current_load": 0,
    "location": "loading_dock",
    "license_plate": "DT-001",
    "mileage": 45280,
    "next_maintenance": "2024-10-15"
  }
}

Sensor Example¶

{
  "id": "temp_sensor_01",
  "type": "sensor",
  "name": "Oven Temperature Sensor",
  "emoji": "🌡️",
  "properties": {
    "sensor_type": "temperature",
    "current_reading": 180,
    "min_range": -20,
    "max_range": 300,
    "unit": "celsius",
    "accuracy": 0.5,
    "location": "oven_chamber",
    "calibration_date": "2024-08-15",
    "digital_output": true
  }
}

Task Interactions¶

Modern Interaction System¶

The interaction system provides powerful ways to modify object properties:

Property Changes¶

{
  "interactions": [
    {
      "object_id": "mixing_bowl",
      "property_changes": {
        "state": { "from": "empty", "to": "filled" },
        "contents": { "from": "", "to": "flour_water_mixture" },
        "weight": { "delta": 2.5 }
      }
    }
  ]
}

Change Types: - from/to: Explicit state transitions - delta: Numerical increments/decrements - set: Direct value assignment - multiply: Proportional changes

Object Creation¶

{
  "interactions": [
    {
      "add_objects": [
        {
          "id": "batch_001",
          "type": "product",
          "name": "Bread Batch #001",
          "properties": {
            "quantity": 12,
            "unit": "loaves",
            "batch_time": "09:30"
          }
        }
      ]
    }
  ]
}

Object Removal¶

{
  "interactions": [
    {
      "remove_objects": ["expired_batch_001", "damaged_equipment"]
    }
  ]
}

Complex Interaction Examples¶

Multi-Object State Changes¶

{
  "id": "production_line_startup",
  "interactions": [
    {
      "object_id": "conveyor_belt",
      "property_changes": {
        "state": { "from": "stopped", "to": "running" },
        "speed": { "set": 1.5 }
      }
    },
    {
      "object_id": "quality_scanner",
      "property_changes": {
        "state": { "from": "standby", "to": "active" },
        "scan_rate": { "set": 60 }
      }
    },
    {
      "object_id": "production_display",
      "property_changes": {
        "active": { "set": true }
      }
    }
  ]
}

Economic Transactions¶

{
  "id": "purchase_materials",
  "interactions": [
    {
      "object_id": "flour",
      "property_changes": {
        "quantity": { "delta": 100 },
        "cost_total": { "delta": 85.00 }
      }
    },
    {
      "object_id": "company_cash",
      "property_changes": {
        "balance": { "delta": -85.00 }
      }
    }
  ]
}

Digital Object Movement¶

{
  "id": "move_digital_asset",
  "interactions": [
    {
      "object_id": "inventory_bot",
      "property_changes": {
        "position": {
          "from": { "x": 10, "y": 0, "z": 5 },
          "to": { "x": 25, "y": 0, "z": 12 }
        },
        "battery_level": { "delta": -2.5 }
      }
    }
  ]
}

Physical Actor Movement¶

Actors can move between physical locations using two methods:

Method 1: Property Changes (Timeline-Aware) Track location changes through the timeline using property_changes:

{
  "id": "move_to_warehouse",
  "actor_id": "forklift_operator",
  "start": "09:00",
  "duration": 5,
  "location": "warehouse",
  "interactions": [
    {
      "object_id": "forklift_operator",
      "property_changes": {
        "location": {
          "from": "loading_dock",
          "to": "warehouse"
        }
      }
    }
  ]
}

The validation system simulates the timeline and tracks the actor’s location changes, ensuring subsequent tasks have the actor in the correct location.

Method 2: Movement Task Type Use the dedicated movement task type for explicit movement actions:

{
  "id": "travel_to_oven",
  "type": "movement",
  "actor_id": "baker",
  "start": "09:00",
  "duration": 2,
  "from_location": "prep_area",
  "to_location": "oven_area",
  "movement_speed": 1.5
}

Movement Task Properties: - type: Must be “movement” to identify this as a movement task - from_location: Starting location (must match actor’s current location) - to_location: Destination location - movement_speed: Optional speed in meters/second for realistic duration calculation

When to Use Each Method:

Use Property Changes when: - Movement is part of a larger task action - You want to combine location change with other property updates - Movement is incidental to the task’s primary purpose

Use Movement Task Type when: - Movement is the primary purpose of the task - You want to explicitly show travel time in the timeline - You need to track movement speed or distance - The movement needs to be visible as a distinct activity

Complete Movement Example:

{
  "simulation": {
    "layout": {
      "areas": {
        "prep_area": {
          "name": "Preparation Area",
          "type": "physical",
          "coordinates": { "x": 0, "y": 0, "width": 10, "height": 5 }
        },
        "oven_area": {
          "name": "Oven Area",
          "type": "physical",
          "coordinates": { "x": 15, "y": 0, "width": 8, "height": 5 }
        }
      }
    },
    "objects": [
      {
        "id": "baker",
        "type": "actor",
        "name": "Baker",
        "properties": {
          "location": "prep_area",
          "cost_per_hour": 25
        }
      },
      {
        "id": "oven",
        "type": "equipment",
        "name": "Commercial Oven",
        "properties": {
          "location": "oven_area",
          "state": "ready"
        }
      }
    ],
    "tasks": [
      {
        "id": "prep_dough",
        "actor_id": "baker",
        "start": "09:00",
        "duration": 20,
        "location": "prep_area"
      },
      {
        "id": "walk_to_oven",
        "type": "movement",
        "actor_id": "baker",
        "start": "09:20",
        "duration": 2,
        "from_location": "prep_area",
        "to_location": "oven_area"
      },
      {
        "id": "bake_bread",
        "actor_id": "baker",
        "start": "09:22",
        "duration": 30,
        "location": "oven_area",
        "interactions": [
          {
            "object_id": "oven",
            "property_changes": {
              "state": { "from": "ready", "to": "baking" }
            }
          }
        ]
      }
    ]
  }
}

In this example: 1. Baker starts in prep_area, prepares dough 2. Movement task explicitly shows 2-minute walk to oven_area 3. Baker’s location is updated by the movement task 4. Baking task can now proceed because baker is in oven_area with the oven

Production Recipes¶

Define complex production requirements:

{
  "production_recipes": {
    "artisan_bread": {
      "ingredients": {
        "flour": 2.5,
        "water": 1.8,
        "yeast": 0.2,
        "salt": 0.05
      },
      "equipment_required": ["mixer", "oven"],
      "production_time": 180,
      "skill_level": "intermediate",
      "yield": 1
    }
  }
}

Validation Integration¶

The UOM works closely with the validation system to ensure:

Schema Compliance¶

All required fields are present
Data types match specifications
Object references are valid

Logical Consistency¶

State transitions are realistic
Resource flows balance properly
Timing constraints are respected

Economic Viability¶

Cost and revenue properties enable profitability analysis
Resource consumption aligns with production output
Labor costs reflect realistic market rates

Best Practices¶

Object Design¶

Use descriptive IDs: industrial_mixer_01 vs mixer1
Include relevant properties: Don’t over-engineer, but include what matters
Set realistic initial values: Base quantities and costs on real-world data
Plan for scalability: Design objects that can handle process variations

Task Interactions¶

Prefer modern interaction format: More explicit and flexible
Group related changes: Combine multiple property changes in one interaction
Include validation properties: Use from values to enable state validation
Document complex interactions: Use clear task names and descriptions

Custom Types¶

Follow naming conventions: Use clear, descriptive type names
Define standard properties: Establish patterns for similar objects
Avoid reserved types: Don’t conflict with system-internal types
Document custom schemas: Explain your custom types for other users

Economic Modeling¶

Include all costs: Labor, materials, overhead, equipment depreciation
Use realistic prices: Base on market research or industry standards
Account for waste: Include scrap rates and efficiency factors
Plan for scenarios: Model different price points and volumes

The Universal Object Model provides the foundation for creating accurate, realistic, and business-ready process simulations that can guide real-world automation decisions.