Skip to main content

​
Overview

A Model Node is a component that embeds another simulation model inside the current one. Instead of duplicating components across many models, you define a sub-model once — a production cell, an assembly line, a department — and embed it wherever you need it. Changes to the sub-model propagate everywhere it’s used. This is the architecture for complex facilities: model a single cell rigorously, compose a department from copies of that cell, compose a facility from copies of the department. Without hierarchical modeling, a complex operation means thousands of components on a single canvas. With it, you get a clean decomposition that mirrors how your operation is actually organized.

​
When to Use Model Nodes

  • Repeated physical structure — your facility has five identical production cells. Model one, then embed it five times via Model Nodes.
  • Reusable templates — standard sub-processes (QC inspection, packaging, kitting) that appear across many models. Define once, reuse across models and even across factories via export/import.
  • Scale — once a model passes ~50-100 components, hierarchical decomposition becomes the only way to keep it navigable.
  • Team division — one person owns the line-level sub-model, another owns the facility-level composition. Model Nodes let them work in parallel.

​
How a Model Node Connects to Its Parent

A Model Node exposes inputs and outputs that the parent model can connect to. Inside the sub-model, those inputs and outputs map to specific components. When you connect an upstream Process to a Model Node’s input, entities flow into the sub-model, through its internal logic, and out its output back into the parent flow.

​
Mapped Connections

The key concept: inputs and outputs of a Model Node are mapped to components inside the sub-model. You can change the sub-model’s internal structure without breaking the parent — as long as the inputs and outputs stay mapped to something valid, the parent model keeps working.

​
Shared Resources

A Resource can be shared between a parent and a sub-model. This matters because many real-world resources (operators, shared equipment) serve multiple cells. Define the resource once at the parent level and let embedded Model Nodes draw from it.

​
Bridged Topics

Topics can be bridged across the parent/child boundary. This lets an event published inside a sub-model be received in the parent, or vice versa. Essential when the sub-model can’t be fully self-contained.

​
Aliased State Variables

State Variables can be aliased: a state variable declared at the parent level can be referenced from inside the sub-model under a different name. This keeps sub-models decoupled (they reference their own internal names) while still letting them participate in parent-level state.

​
Qualified Component Paths

Components inside a Model Node are addressed by a qualified path using :: as the separator. A component named process_1 inside a Model Node named model_node_1 is referenced as model_node_1::process_1 anywhere outside its parent sub-model. This matters in three places:
  • Queries against simulation data. Component IDs in entity_lifecycle, process_activity, and other dataframes use the qualified form. A SQL filter on component_id = 'process_1' misses every instance inside a Model Node; use component_id = 'model_node_1::process_1' or match with a LIKE pattern.
  • Schedule material releases. A scheduled material release to a Source inside a sub-model must name the Source with its full path: model_node_1::source_1.
  • Event system references. Event Hooks, topic names, and state variable references that cross the parent-child boundary use qualified paths. A hook on model_node_1::buffer_1 fires based on that specific instance inside that specific Model Node.
For deeply nested structures, paths chain: facility::line_3::cell_2::process_1 addresses a process three levels down. Inside a sub-model, you can reference local components by their bare name — the qualified prefix is only needed when crossing the parent-child boundary. This keeps sub-models reusable; they don’t need to know what name their parent gave them.

​
Common Patterns

Cell template. A single “production cell” sub-model is created once with canonical equipment. The facility model instantiates it five times, each with different parameters passed in via constants or attributes. Department composition. Build a “fabrication” model and an “assembly” model separately, then compose them in a facility model with connections between their outputs and inputs. Progressive detail. Start with a coarse facility model — a few Model Nodes, each representing a department as a black box. As you need more fidelity, replace a Model Node’s internal sub-model with a more detailed one. The parent doesn’t change.

​
Tips

  • Treat sub-models as libraries. Once a sub-model is stable, avoid editing it casually — changes propagate to every instance.
  • Parameterize via constants or attributes. Don’t hardcode values that differ between instances. Pass them in so each Model Node can behave differently.
  • Name inputs and outputs clearly. The parent model connects by name — clear names prevent wiring mistakes.
  • Keep the top level thin. A well-organized facility model is mostly Model Nodes with a little glue between them. If your top level has hundreds of direct components, you’re losing the benefit.