Command line

Diokle was called DAEdalus until this release. The diokle command, the Python diokle package and the Diokle Modelica library use the new name; scripts that call daedalus need updating.

diokle is one executable with a command per task. Every command takes the model sources (.mo files or directories, loaded recursively) and the model's full name:

diokle <command> [sources...] -m <Model> [options]

Only the classes a model needs are parsed, so pointing at a large library costs little; parsed library files are cached on disk between runs (~/.cache/diokle; DIOKLE_CACHE moves it and DIOKLE_NO_CACHE turns it off).

In plain terms: each command does one job on a model, such as checking it, simulating it or listing its unit problems. The table below lists them, and the options further down change how each one runs.

#Commands

The same compiler is also a Python package, import diokle, for notebooks and scripts: see Python API.

#Reviewing Modelica changes

diokle textconv FILE prints a .mo file with one statement per line, with whitespace collapsed and comments removed; string literals such as descriptions and documentation are kept. The repository's .gitattributes maps *.mo to the modelica diff driver, which uses it. Git keeps the driver setting per clone, so run once in each clone (with diokle on the PATH):

git config diff.modelica.textconv 'diokle textconv'

Then git diff and git log -p show one statement per line, and a reflowed declaration with no change in content shows no diff. Use git diff --no-textconv for the raw text.

#Formatting

diokle fmt lays out Modelica source: indentation by class and section, one statement per line, and annotations split over lines of at most 100 columns. It changes whitespace and line breaks only. Comments and string literals are kept as they are, and the output has the same tokens as the input.

diokle fmt Motor.mo                    # print the formatted file
diokle fmt --write library/Diokle      # rewrite every .mo file that changes
diokle fmt --check library/Diokle      # list the files that would change; exit 1 if any

--write skips a file whose formatted text no longer parses, and leaves that file as it is. The workbench formats the open class on Ctrl+S, and the language server (diokle lsp) answers the editor's whole-document format request with the same layout.

#Simulating

# Experiment annotation defaults
diokle simulate library/Diokle -m Diokle.Examples.LandingGear.SinkRates -o sink.mat

# Override the interval, tolerance, method and parameters
diokle simulate library/Diokle -m Diokle.Examples.TorqueConverter.StallTest \
    --stop 6 --tol 1e-8 --method dopri5 -p engine.J=0.3 -o stall.mat

# CSV of selected variables
diokle simulate library/Diokle -m Diokle.Examples.QuarterCar.BumpComparison \
    -o bump.csv --vars clean.body.s,aerated.body.s

translated in 11.7 ms; simulated in 7.2 ms (158 steps, 10 rejected (0 Newton), 378 f-evals, 3 jacobians, 2 events)

.mat results use Dymola's dsres layout, so Dymola, OMEdit, DyMat, ModelicaRes and existing post-processing scripts read them.

Add --profile to see where the solver spends its steps and time, and --method auto to let it switch between Dopri5 and BDF; see Performance analyzer and Solvers.

#Starting from a previous result or a steady state

A run normally starts from the model's initialization. Two options start it from other states instead. The algebraic variables are recomputed from the states, and the log notes each state whose value replaces the one initialization gave.

diokle simulate model.mo -m Plant --stop 100 -o warmup.mat
diokle simulate model.mo -m Plant --restart warmup.mat --stop 200 -o continued.mat
diokle simulate model.mo -m Plant --steady-start --stop 200 -o settled.mat

• --restart FILE starts from the states of a .mat result, at its last time or at --restart-at T. The run starts at that time unless --start is given. Every state of the model must be stored in the result.
• --steady-start starts from the steady state at the start time (see Steady states).

A parameter whose value changes the structure, such as a Boolean or Integer parameter, or a Real parameter that a fixed attribute depends on, is translated again with -p rather than changed at run time.

#Libraries

The bundled Diokle library is a source directory like any other, and so is the Modelica Standard Library:

git clone -b v4.1.0 --depth 1 https://github.com/modelica/ModelicaStandardLibrary msl
diokle simulate msl/Modelica msl/ModelicaServices msl/Complex.mo \
    -m Modelica.Mechanics.Rotational.Examples.CoupledClutches -o clutches.mat

-L DIR adds a library directory the same way, and DIOKLE_LIB (or --lib) points at the bundled library.

#Steady states and trim

diokle steady crates/diokle-core/tests/models/steady.mo -m Steady.Pendulum \
    --free tau --target angle=0.5

trim of Steady.Pendulum at t = 0 (2 Newton iterations, residual 0.000e0)

states:
  phi = 0.5
  w   = 0

free variables:
  tau = 3.7625316269657856

targets:
  angle = 0.5 (target 0.5)

eigenvalues of the state Jacobian (stable):
  -2.343750e-1 - 3.272067e0i
  -2.343750e-1 + 3.272067e0i

The torque that holds the pendulum at 0.5 rad is m·g·L·sin(0.5) = 3.76 N·m, and the equilibrium is stable. Without --free and --target, steady finds the equilibrium for the inputs as they are. See Scripts and steady states.

#Scripts

diokle run regression.mos --msl ~/ModelicaStandardLibrary

runs a Dymola or OpenModelica .mos script: loading files and libraries, translating, simulateModel and simulate, parameter sweeps with simulateExtendedModel, linearizeModel, steadyState and trim, with loops and conditionals. See Scripts and steady states.

#Testing a whole library

diokle test-library library/Diokle -m Diokle

Each model runs in its own process, in parallel (--jobs N, default: all cores), with a time limit (--timeout S, default 60). --junit FILE writes a JUnit XML report, one test case per model. --baseline FILE lists the models that must pass and fails the run if any stops passing; --write-baseline FILE records the models that pass now. CI runs this on every pull request, and a nightly job runs the MSL examples against their reference results (see Modelica Standard Library).

#Reference pages

diokle doc writes Markdown reference pages from the sources, without translating them: each class's documentation, parameters (with units and defaults), components, connections, experiment settings and nested classes, with links between the pages.

diokle doc library/Diokle -m Diokle.Blocks.Math.Gain         # one page, to stdout
diokle doc library/Diokle -o docs/reference                  # index.md and one page per class

The pages are plain Markdown, so they can be committed, published with any static site generator, or regenerated in CI and compared with the committed copy. A class's Documentation(info=...) HTML is reduced to headings, paragraphs, lists, emphasis, links, images and code; other markup is dropped.

#Model checks

diokle lint runs model-quality checks on the sources, without translating them, so it is fast enough to run on every change:

diokle lint library/Diokle                                  # report, exit 0
diokle lint library/Diokle --allow description --allow unit # leave two rules out
diokle lint library/Diokle --strict --format github         # fail on findings; GitHub annotations
diokle lint --list-rules

--format json gives the findings as data. --strict exits 1 when any finding remains. A top-level example is one that no other class extends or instantiates; parts keep their connectors open for their user. CI gates the experiment and unconnected rules on the Diokle library, and shows the remaining findings (documentation, descriptions and units) as annotations.

#Options

#Performance

Models run as machine code: the hot tapes (derivatives, outputs, zero crossings and algebraic loops) are compiled with Cranelift when the simulation starts, which takes a few milliseconds for most models. The results are bit for bit the same as the interpreter's (--no-jit); across the 555 MSL, Diokle and MultiBodyVehicle examples the total run time drops by about 35%, and by half or more on multibody models (SevenPostRig 2.5 s to 1.2 s, EngineV6 5.7 s to 2.3 s).

The benchmark is tools/gen_chain.py: a chain of N masses and spring-dampers driven by a sine force, a stiff system with 2N states, simulated for 1 s with BDF at tolerance 1e-6.

python3 tools/gen_chain.py 2000 > chain.mo
diokle simulate library/Diokle chain.mo -m Chain --stop 0.2 -o chain.mat