Build and run a twin

This is the loop a person repeats: generate from a command file, put behaviour into the skeletons, compile, run, read the traces. Every command below was run on this machine.

1. Generate the twin folder

vsiBuild reads a command file and writes the twin folder named by its set digitalTwinName line under the folder named by set workspaceDir. The command files in this workspace end with generate -overwrite -no-build and quit, so generation is separate from compiling and takes about 15 seconds for 63 components.

vsiBuild -c -f TWIN.vsi.cmd

Run it from the folder that holds the command file. In a script, redirect its standard input from the same command file and its output to a log; started interactively it opens its own console. A modal dialog appears on licence failure, so give a scripted run a bounded wait. generate -overwrite on an existing folder replaces the generated sources and throws away anything written into the user regions: re-apply the glue after every generate.

Two vendor facts about the grammar, both learned by running the binary rather than reading the PDF: help, help -gateway NAME and help -command NAME inside a command file return the real syntax in about two seconds; and a repeated generate without -overwrite does nothing and says nothing. The grammar as accepted is in reference/command-grammar.

2. Put behaviour in

Either author it in the five user regions of each component's skeleton (see building-a-twin/writing-component-behaviour) or apply the workspace glue, which writes counters, monitors and a trace writer into every component from the wiring:

python twin_glue\apply_glue_generic.py TWIN.vsi.cmd D:\wfpy\TWIN

It reports how many components it patched, which are Python, which CAN consumers it muted and the period it gave each bus, and writes glue_wiring.json into the twin folder for the checker. Run it again after any regenerate. It rewrites all three regions it owns every time, so an older version's glue never lingers.

3. Compile

From the twin folder, with the mingw64 bin on PATH:

mingw32-make compile build

This compiles every client and the fabric server without regenerating anything. Measured: 63 C++ clients in 390 to 440 seconds; 7 clients in 40 to 120 seconds; a Python component adds a gateway extension build (pythonGatewaysN\...\VsiPythonGateways.cp313-win_amd64.pyd) of about a minute. Success is 0 errors in the log and one VsiClientN.exe per C++ component under vsi.build\_objs. In PowerShell, capture the build's output with Start-Process and redirected output files; capturing it into a variable stalls the build step.

Copy-Item preserves file times, so a source copied over an older one may not be recompiled by make; touch it or delete the object.

4. Run

vsiSim TWIN.dt --batch --run

Exits by itself after the total simulation time. A 63-component twin takes about 100 s of which about 65 s is every client connecting; a 7-component one about 10 to 20 s. Do not use mingw32-make sim: it waits at the control prompt for a run that never comes under a redirected console. Details and every prompt command: simulation-control-commands.

5. Read the result

Judge by artefacts, not exit codes:

1. vsi.sim\_logs\check.TWIN.log ends with Simulation stopped by user and Total SystemC time = 10000000.
2. One COMPONENT_trace.csv per glued component in vsi.sim\_logs, 101 lines each (a header and 100 steps).
3. The checker passes:

python twin_glue\check_traces.py D:\wfpy\TWIN --traces D:\wfpy\TWIN\vsi.sim\_logs

It prints one line per consumed signal (ok or FAIL, with the lag and the change count it needed) and a producer-rate line for any producer off its declared period, then a RESULT line. PASS needs zero FAIL, zero MISSING and zero rate_bad. What each check means is in verifying-a-run.

6. Keep the evidence

Twin folders are not tracked. Copy the traces, glue_wiring.json and the checker output to innexis-vsi\runs\DATE-TIME-TWIN-RESULT\ and add a row to runs\README.md, so the result survives the next regenerate.

Rebuild only what changed

• Changed the command file: generate again, re-apply glue, compile, run.
• Changed only glue or behaviour in user regions: re-apply glue (or edit), compile, run. For a Python component there is nothing to compile; the file runs as edited.
• Changed only the checker or a period in the glue: the twin needs re-applying and compiling, because the period is baked into the generated call.