Action Diagrams

Overview

An Action Diagram shows how a parent Action is carried out: its child Actions in order, the points where the flow splits into parallel paths or alternatives, the loops, the Input/Outputs that pass from one Action to another, the Resources each Action uses, and the Assets that perform the work. It is the LML behavior diagram and the executable model of Holarch: the Simulator runs exactly what the diagram shows.

The diagram is a view of the model. Every Action on it is a child of the root Action (decomposed by), every line to an Input/Output is a generates or receives relationship, and every line to a Resource is a consumes, produces or seizes relationship. Adding, moving or deleting shapes changes those entities and relationships, and every change is one undo step.

The same flow drives three other views: the Functional Flow Block Diagram (FFBD), the SysML Activity Diagram and the Timeline Diagram. Edit the flow in any of them and the others follow.

Concepts

The flow

A flow runs from a green Start pill on the left to a red End pill on the right. Between them is a sequence of elements joined by arrows. An element is one of:

Parallel, SYNC and OR elements hold branches: each branch is its own sequence and can hold any element, including further constructs. A LOOP holds one sequence, its body.

The OR, SYNC and LOOP construct entities are decomposed under the root like the steps, but they are not steps: they never appear as Action boxes, and views such as the Timeline skip them. They exist so a decision, synchronization point or loop can carry a name, a script and (for SYNC) a timeout.

Items around the flow

What each shape shows

• Action box: the number (top), the name, and one line below: the Duration (for example 1 minute), or the performing Assets when Assets is on.
• { } in purple at the lower left: the Action or construct has a simulation script.
• A small decomposed icon at the upper right: the Action has its own child flow. Click the icon to open it.
• Branch labels: for an OR, the guard name and its probability (Yes (75%)) or condition (Low [< 20], [else]); for Parallel and SYNC, the branch name and its Branch Asset.
• Loop text under the return arrow: Continue (×4), Continue (50%), Continue while Battery Charge > 20, Continue (script) or Continue (ask). Exit marks the way out.
• The construct's name is shown in italics next to OR, SYNC and LOOP blocks.

How the diagram maps to LML

The Action class has three attributes: Start (date and time), Duration (value or distribution plus Seconds, Minutes, Hours, Days, Weeks, Months or Years) and Percent Complete. A Resource has Units, Initial Amount, Minimum Amount and Maximum Amount. An Input/Output has Size, Units, Type and Value.

How to use it

When and why

Build an Action Diagram after you have a set of functions, usually from Functional Analysis of the requirements, and before you allocate them to the physical architecture. It answers: in what order do the functions run, which run in parallel, where does the system decide, what does each function need and produce, and how long does the whole thing take?

Use it at each level of decomposition: a top-level operational scenario (a mission timeline, a use case), then one diagram per function that needs its own detail. Because the diagram is executable, it is also the place to check timing and resource requirements early, with the Simulator, before hardware exists.

Build a flow from scratch

1. Open Diagrams at the bottom of the rail and click + Create Diagram. In Choose Which Type of Diagram to Create, pick Action Diagram (on the All or LML tab).
2. In Specify New Root, keep Root Entity Class = Action, enter a Number and Name (for example OPS and Run Nominal Imaging Pass) and click Create. Result: the diagram opens with Start and End and the hint Drag a construct here or use + Action.
3. Click + Action ▾ → New Action…, type the name in Add Action and click OK (or press Enter). Result: a numbered Action box appears in the flow (numbers continue from the parent's number: OPS.1, OPS.2, …) and the new Action is a child of the root.
4. Keep the new Action selected and add the next one the same way: + Action always inserts after the selected element.
5. To run steps at the same time, select the step after which they start and click + SYNC (or + Action ▾ → Parallel (no entity) when you do not need a timeout or a name). Two empty branches appear. Click a branch line to select it, then + Action ▾ → New Action… to add a step to that branch. Click + Branch for a third branch.
6. For a decision, click + OR and enter the question (for example Contact in view?). Two branches, Yes and No at 50% each, appear. Select the OR to set the guard names and probabilities in the inspector.
7. To repeat a step, select it and click + LOOP, then enter the loop name. Result: the step is wrapped in a loop that runs twice. Set the number of iterations, or another condition, in the inspector.
8. Set durations: select an Action and fill in Duration under Attributes in the inspector, or Shift-click several Actions and click Duration… to give them one value.
9. Choose ⚙ → Check Diagram… to list Actions without a Duration and items that are not connected.

Build a flow by dragging from the palette

The palette on the left holds the constructs and the item types.

1. Drag Serial (Action) onto any line of the flow. The drop line highlights while the item is over a valid place. Result: a "New Action" is inserted at that point and its name field in the inspector is selected so you can type the name.
2. Drag Parallel, Or, Sync, Loop or Exit onto a line in the same way.
3. Drag Input/Output onto an Action to create an I/O that the Action generates, or onto empty canvas to place an unconnected I/O.
4. Drag Resource onto an Action to create a Resource that the Action consumes (Amount 1), or onto empty canvas.
5. Drag Branch Asset onto a branch line of a Parallel or SYNC and choose the Asset. Result: the Asset performs every Action on that branch.
6. Type in the Existing box to find Actions, Input/Outputs, Resources and Assets already in the model, then drag one in: an Action onto a line, an I/O or Resource onto an Action or the canvas, an Asset onto a Parallel or SYNC branch line.

With the keyboard, focus a palette item and press Enter or Space: constructs are added at the end of the main flow, Input/Outputs and Resources at the center of the view.

Connect Input/Outputs and Resources

Select an Action: a green handle appears above it. Drag the handle:

• onto another Action: Holarch creates a new Input/Output that the first Action generates and the second receives. While you hover, the target box shows two halves: release on the Trigger (top) half for a triggering input, or on the Optional (bottom) half for an optional one;
• onto an existing Input/Output: the Action generates it;
• onto a Resource: the Action produces it (Amount 1);
• onto empty canvas: Holarch creates a new output of the Action.

Select an Input/Output and drag its handle (below the shape) onto an Action to make that Action receive it; the top half sets Trigger, the bottom half Optional. Dragging onto an Action that already receives it changes only the Trigger setting.

Select a Resource and drag its handle (above the shape) onto an Action: the Consumes (top) half creates consumes, the Seizes (bottom) half seizes. Switching between them keeps the amount.

After a connection that creates a new I/O, the I/O is selected and its name field is ready for typing. Set the amount of a resource link in the Action's Relationships tab in the inspector (the relationship attribute Amount), or in the Resource's.

Drag an Input/Output or Resource shape to place it where you want; the position is saved with the diagram. Reset Placement in its inspector (or ⚙ → Reset I/O & Resource Placement for all) returns it to the automatic layout above or below the Actions that use it.

Assign performers

• Select an Action, open the Relationships tab in the inspector and add performed by an Asset; or
• Drag a Branch Asset onto a Parallel or SYNC branch, or select the Parallel/SYNC and click + Asset next to the branch in the inspector.

Turn on Assets in the toolbar to show performers under each Action name.

Decompose and drill down

• Decompose one Action: select it and click Decompose (or double-click a decomposed Action, or click its decomposed icon). Result: that Action's own Action Diagram opens; build its child flow there. ▲ Parent in the top bar returns to the parent diagram.
• Group steps into a new child: Shift-click two or more elements that are next to each other on the same line, then click Decompose (group). Result: the elements move into a new child Action named "New Action" with its own flow, and the toast Grouped into a new child Action — rename it in the panel. appears with the name field selected.
• Flatten: select a decomposed Action and click Flatten (or Flatten in the inspector). Its child flow replaces it in this diagram. Choose Keep Entity to keep the emptied Action in the model (outside this diagram) or Delete Entity to delete it.

A decomposed Action runs its child flow in the Simulator; its own Duration is not used.

Simulate and validate

1. Click ▶ Simulate ▾ → Discrete Event to watch one timed run, or Monte Carlo for many runs. The Simulator opens with this Action as the root.
2. Before the first run, ⚙ → Check Diagram… shows what the Simulator will treat as missing: Actions without a Duration simulate as 0, I/Os that no Action generates leave their receivers waiting (a deadlock), Resources that nothing uses are listed.
3. In the Simulator, a run that waits forever is reported as a deadlock with the reason (waiting for I/O … (never generated) or waiting for … (never available)). Fix the diagram, for example by turning a trigger into an optional input, and run again.

Worked example: the CubeSat EO-1 imaging pass

The demo project (Manage Projects → Project Files ▾ → Create Demo Project) contains the Action Diagram OPS Run Nominal Imaging Pass. Open it from Behavior → Action Diagrams.

The flow:

1. OPS.1 Transmit Imaging Plan (Ground Station, triangular 4–9 minutes, most likely 6), OPS.2 Receive Imaging Plan (UHF Transceiver, 1 minute) and OPS.3 Load Command Schedule (C&DH, 2 minutes) run in sequence.
2. A Parallel runs OPS.4 Rotate to Target (ADCS, normal 3 ± 0.5 minutes) and OPS.5 Prepare Camera (Payload Camera, 5 minutes) at the same time; both receive Command Schedule as a trigger.
3. A LOOP named Each target runs OPS.6 Capture Image Strip and OPS.7 Encode and Store Image four times (Continue (×4)).
4. An OR named Contact in view? sends the flow to OPS.8 Transmit Image Data on Yes (75%) or OPS.9 Hold Data Onboard on No (25%).
5. A final Parallel recharges the battery (OPS.10) while the ground receives and processes the data (OPS.11, OPS.12).

Resources: Battery Charge (Wh, initial 62, minimum 23, maximum 77) is consumed by OPS.4 (1.5), OPS.5 (0.8), OPS.6 (2), OPS.7 (0.3) and OPS.8 (6) and produced by OPS.10 (30). Data Storage (GB) is produced by OPS.7 (2.5) and consumed by OPS.8 (8). Image Data Package is an optional input of OPS.11, so a pass without contact does not deadlock the ground segment.

Try these changes:

1. Select the OR and change Yes to 60 and No to 40. Result: the branch labels read Yes (60%) and No (40%) and the inspector shows Total 100%.
2. Select the LOOP and set Iterations (count) to 6. Result: the loop text reads Continue (×6).
3. Choose ▶ Simulate ▾ → Monte Carlo and run it: more targets per pass consume more battery, and the Statistics panel shows the longer pass time.
4. Turn on Assets to see each performer, then choose ⚙ → Generate Asset Diagram. Result: a new Asset "Run Nominal Imaging Pass (Physical Context)" with the performing Assets as children and Conduits for every I/O that passes between two of them, and its Asset Diagram opens.

Tips and good practice

• Name Actions as verb + object (Capture Image Strip), I/Os as nouns (Image Strip), and OR guards as answers to the OR's question.
• Keep each diagram to about seven to twelve elements. Group detail into child Actions with Decompose (group).
• Use Parallel (no entity) unless you need a timeout, a name or a script; use SYNC for those.
• An OR in probability mode must total 100%. When probabilities are unknown, choose None (prompt or random) and let the Simulator ask, or let Monte Carlo use equal probabilities.
• Give every leaf Action a Duration before simulating. Use a distribution (for example =norm.dist(40,6) Seconds) where the time varies.
• Turn a received I/O into Optional when the Action can start without it; otherwise a branch that never produces it deadlocks the run.
• Number children in flow order with ⚙ → Auto Number… and Number in action-flow order.

Common mistakes

How it connects to other features

• Fed by: Functional Analysis creates the functions (child Actions) and their flow; requirements reach the Actions through satisfied by. Assets and Resources come from the architecture.
• Feeds: the Simulator (time, cost, resource levels, Asset utilization, requirement checks), the FFBD and Activity Diagram (same flow), the Timeline Diagram (schedule from Start and Duration), the Sequence Diagram (lifelines are the performing Assets, messages the I/Os), Generate Asset Diagram (physical context and Conduits), the N² Diagram (I/Os between functions) and IDEF0 (inputs and outputs).
• Traceability: every Action shows its requirements in the inspector's Relationships tab (satisfies); the RVTM and Traceability Matrix read the same relationships.

The editor

The Action Diagram uses the shared diagram editor (see Diagrams): the toolbar row, the palette on the left, the canvas and the inspector on the right.

Top bar

• Diagram type selector: the same root Action in another diagram type that applies to Actions (Hierarchy, Spider, Tree, Risk, Timeline, Action, Sequence, Use Case, N2, IDEF0, ICOM (A0), Activity, FFBD).
• ▲ Parent: opens the Action Diagram of the parent Action. Shown only when the root has a parent Action.

Toolbar

The toolbar is one row in groups. When the window is narrow, items move into ⋯ (More actions); Export ▾ and ⚙ always stay visible.

⚙ Diagram settings

Palette

The palette (title Palette, hint Drag onto a line or a shape) lists:

Under Existing, type to find Actions, Input/Outputs, Resources and Assets (up to 80 matches, root and construct entities excluded) and drag them in. Below the palette is the Annotations section shared by all diagrams. × in the palette header hides it (⚙ → Show Palette brings it back).

Canvas gestures

Inspector

Action, Input/Output, Resource or Asset selected: the shared entity panel with Name, Number, Description, Open Entity View, Open ▾ (Entity View and every other diagram of this entity), the actions below, Attributes (open for Actions), and the Relationships, Metadata and Comments tabs. The relationships this diagram manages (consumed by, decomposed by, generated by, performed by, produced by, received by, seized by) are locked in the Relationships tab so the diagram and model stay in step.

OR selected (OR (Decision)):

• Decision name: the OR entity's name.
• Decision type: Probability, Resource condition, Script or None (prompt or random).
• Resource (Resource condition only): the Resource whose amount is compared.
• Branches: a guard name per branch and, by type, a probability (0–100 %) or an operator (==, !=, >, <, >=, <=, else) and a value. The total line reads Total 100% or the warning Branches must total 100% but currently total N%.
• Edit Script…/Add Script… (Script type): onEnd() returns the name of the branch to take.
• None type: With "Prompt" decisions the simulator asks which path to take; when automated it picks a branch at random.
• + Add Branch, Open Entity.

SYNC selected: Name, Duration (timeout) (Optional: the SYNC ends after this time and stops any branch still running), the note N branches run concurrently; flow continues when all finish., one row per branch with the branch name and + Asset (or ⟂ Asset name and × to remove it), Edit Script…/Add Script…, + Add Branch, Open Entity. Parallel selected shows the same without the entity fields. When a branch is selected: Branch N selected — + Action adds to it.

LOOP selected:

• Name / condition.
• Continue condition: Iterations, Probability, Resource condition, Script or None (prompt or random).
• Iterations (count) (minimum 1), Probability to continue (%), or Resource plus continue while amount with an operator and value.
• Script: Before each pass onEnd() is called; returning true runs the body again.
• None: With "Prompt" decisions the simulator asks for the number of iterations; when automated it runs 0–2 passes at random.
• Edit Script…/Add Script…, the note An EXIT inside the body ends the loop early., Open Entity.

EXIT selected: Ends the enclosing LOOP (or this flow) when reached.

Several elements selected: N elements selected, Decompose (group into new child Action), Group Apply Duration…, Remove from Diagram.

Simulation scripts

Edit Action Script… (Action) and Edit Script…/Add Script… (OR, SYNC, LOOP) open the script editor. Add onStart(), Add prompt(), Add onEnd() and Add duration() insert empty hook functions; Tab inserts two spaces; Save stores the script (an empty script removes it). The hooks:

• onStart() runs when the element starts.
• prompt(p) builds a question for the user: p.setTitle(), p.addEnumInput(title, name, choices, default), addTextInput, addNumberInput, addBooleanInput.
• onEnd(response) runs at the end. An OR returns the name of the branch to take; a LOOP returns true to run the body again.
• duration() returns the duration of the Action.

Scripts can call Sim.getEntityByName(n), Sim.getAmount(name), Sim.setResourceByName(name, v), Sim.getCurrentTime(), Sim.getCurrentCost(), print(x) and globals.put(k, v) / globals.get(k). Top-level variables persist for the run and Math.random uses the run's seeded generator. The full API, the sandbox and the trust prompt are in Simulation.

Delete and remove

Deleting never removes more than you confirm, and every choice is one undo step.

Removing an Action from the diagram also removes its decomposed by link to the root, so it is no longer a child; the entity and its other relationships stay.

Keyboard shortcuts

Options and settings

• Show/hide (toolbar toggles and ⚙): I/O, Resources, Assets, Parent I/O and Palette. Saved per diagram and remembered in this browser as the default for new Action Diagrams. Defaults: I/O, Resources, Parent I/O and Palette on; Assets off.
• I/O and Resource positions: saved per diagram; reset with Reset Placement or Reset I/O & Resource Placement.
• Zoom and position: saved per diagram; a diagram opens fitted but at no less than 70%.
• Read-only display: people with the Viewer role see the diagram without the toolbar edit groups, palette, handles or selection panel. They can pan, zoom, search and export.

Messages

Limits

• One flow per parent Action; an Action can appear only once in a given flow (use a LOOP to repeat it).
• The palette's Existing list shows the first 80 matches; type more of the name to narrow it.
• OR probabilities are whole percentages from 0 to 100; loop iterations are whole numbers of at least 1.
• Durations are never negative in simulation: a sampled negative value is drawn again.
• Box select is not available; use Shift-click.

Related pages

• Diagrams: the shared editor, exports and annotations.
• Functional Analysis: functions, the FFBD and its tables.
• Simulation: Discrete Event and Monte Carlo runs, scripts and results.
• SysML Diagrams: the Activity and Sequence Diagrams built on the same Actions.
• Other Diagrams: Asset, Timeline, IDEF0 and N² Diagrams.
• Help: Build an Action Diagram, Action Diagram, Simulation Scripts.