Mocoal (Modelica Component Auto Layout) gives the components of a Modelica model a Placement and its connections a Line. For models
written as text, without graphical annotations: OMEdit shows such a model as an empty diagram, even
when it has many components and connections. After mocoal it shows every component and every
connection.
Two forms, one crate:
- the standalone program
mocoal, - the shared library
libmocoal(C interface, for tools such as OMEdit).
The source is parsed with OpenModelica's Rust parser. Only annotations are changed: comments, formatting and everything else in the file stay as they are.
model Chain
Gain a(k = 2);
Gain b;
Gain c "the last one";
equation
a.u = time;
connect(a.y, b.u);
connect(b.y, c.u);
end Chain;mocoal Chain.mo prints:
model Chain
Gain a(k = 2) annotation(Placement(transformation(origin={-50,0}, extent={{-10,-10},{10,10}})));
Gain b annotation(Placement(transformation(origin={0,0}, extent={{-10,-10},{10,10}})));
Gain c "the last one" annotation(Placement(transformation(origin={50,0}, extent={{-10,-10},{10,10}})));
equation
a.u = time;
connect(a.y, b.u) annotation(Line(points={{-39,0},{-12,0}}));
connect(b.y, c.u) annotation(Line(points={{11,0},{38,0}}));
end Chain;The lines start and end at the connectors of Gain (its u at x = -120, its y at x = 110 in
the icon). The whole file is in test/models/Chain.mo.
Neither the components nor the classes need graphical annotations. The input has no Placement
and no Line, and Gain has no Icon: a class without an icon gets the default size, 20 x 20,
and OMEdit draws it as a box with its name. The result in OMEdit 1.27.1:
examples/Drive.mo is a speed control of an inertia with 8 components of the
Modelica Standard Library, written as text: no annotation at all. mocoal -L ~/.openmodelica/libraries Drive.mo places the 8 components and routes the 8 connections
(examples/Drive-layout.mo): the signal flow from left to right, the
speed sensor's feedback below. In OMEdit 1.27.1:
More in examples/: Drive before and after, and six examples of the Modelica Standard Library, before and after, in OMEdit.
Rust 1.99 (stable) and git.
scripts/fetch-omc.shcargo build --releasetarget/release/mocoal and target/release/libmocoal.{so,dylib} (mocoal.dll on Windows).
macOS arm64: mocoal 1.6 MB, libmocoal.dylib 1.5 MB, no other files needed at run time.
usage: mocoal [options] file.mo|directory ...
mocoal [options] --stdin file.mo
Give the components of Modelica models a placement and the connections a line.
One file without -o, -i or -n: the result is printed.
-o, --output FILE write the result to FILE (one input file)
--stdin FILE read the text of FILE from the standard input (FILE need not
exist; its place finds the libraries next to it)
--stack MB stack of the layout in MB (256); a level of nesting in the
model takes about 3 KB
-i, --in-place change the input files
-n, --dry-run report only, write nothing
-c, --class NAME lay out only this class or package (may be repeated)
-k, --keep keep existing placements and lines, add what is missing
--layout NAME layered (default), spring, grid
--route NAME orthogonal (default), straight, bezier, none
--direction NAME right (default), down
--spacing DX[,DY] space between components (30,20)
--scale S factor on the component size (1)
--no-rotate do not turn two-pin components
--graphics NAME shapes of the Diagram layer: move (default), keep, drop
-L, --library DIR a directory with libraries (may be repeated)
--svg DIR write an SVG preview of every diagram into DIR
-q, --quiet no report
-h, --help this text
--version the version
A directory is searched for .mo files. The report goes to standard error. Exit status: 0, 1 (a
file failed), 2 (command line).
An existing layout is replaced. --keep leaves existing placements and lines and adds the
missing ones.
Classes used by a model are looked up in the file, in its package directory, in the -L
directories, in OPENMODELICALIBRARY and MODELICAPATH, and in ~/.openmodelica/libraries.
char *mocoal_layout(const char *text, const char *file_name, const char *options);
const char *mocoal_message(void);
const char *mocoal_version(void);
void mocoal_free(char *text);mocoal_layoutreturns the new source, orNULLwhen there is no layout.file_namemay beNULLor empty.optionsis a command line as formocoal("--route straight --keep"),NULLor empty for the defaults; a word may be in double quotes (-L "/my libs"). Release the result withmocoal_free.mocoal_messagegives the error after aNULL, and the warnings (one per line) after a layout. The text belongs to the library.- Call the functions from one thread at a time.
interface/INTERFACE.md is the specification: what a caller may rely on, the options, the class lookup, and what an implementation of the library has to do. interface/test_lib.c is a C program that tests it.
The library also exports 3 symbols of the parser crates (omrs_add_runtime_error,
omrs_add_runtime_error_pos, omrs_runtime_abort). They are not part of the interface.
The crate openmodelica_ast (OMCompiler/Compiler/OpenModelica.rs in
OpenModelica) gives the Absyn tree of omc. It is
linked statically: no OpenModelica installation is needed to build or run.
scripts/fetch-omc.sh copies 5 crates (openmodelica_ast, openmodelica_error,
openmodelica_wasi, metamodelica, metamodelica_derive) and 6 builtin .mo files into
omc/ (1.5 MB), at the commit in omc/COMMIT. They are not in this repository.
OPENMODELICA_SRC=<checkout> scripts/fetch-omc.sh takes them from a local checkout, else they
come from GitHub (38 s). A new parser: change omc/COMMIT, fetch, build, run the checks.
- Parse the file (
openmodelica_ast), and tokenize it for the positions of the edits. - Per model, block or class: collect the components that have an icon (connectors, and
components of classes with connectors) and the
connectequations. Ports get their place and colour from the connector'sPlacementand icon in the component's class, base classes included. - Place the components: layered (signal flow from left to right; inputs left, outputs right), spring or grid. Unconnected components go into a grid.
- Route the connections: orthogonal lines around the components, straight lines, or Bezier.
- Write
PlacementandLineinto the annotations. The diagram'sextentis written only when the content does not fit.
Rules:
- A connector of the class itself is placed in the diagram and keeps its place in the icon: the
old
transformationbecomes theiconTransformation. Without a place it gets one on the icon's border (inputs left, outputs right). - Components whose connectors are all acausal (two-pin electrical, mechanical and thermal parts)
are turned by 0, 90, 180 or 270 degrees so that their connectors face their neighbours: the
layout runs, the parts are turned, the layout runs again (up to 3 times). A part with one
connected connector (a boundary, a sink) is turned when that connector is on the left or right of
its icon; one with its connector on top (a ground, a fixed flange) is not.
--no-rotateleaves them unturned. - The shapes of the Diagram layer (
Diagram(graphics={...})) belong to the old layout: a rectangle that held components becomes the frame of those components, a text inside it or up to 25 above it moves with the frame, a small rectangle or ellipse (a junction marker) and a rectangle that holds nothing are dropped, other shapes move with the nearest component. A frame that would cover another component is dropped with its texts.--graphics keepleaves the shapes,--graphics dropremoves them. - A class with only placed connectors and no connections (an interface) is left as it is.
- A component inherited from a base class sits where the base class has it. When the base class is laid out in the same run, that is its new place. The new components go beside the inherited ones (not beside inherited connectors), on the side where the lines to them are shortest; no component or line is placed on an inherited component.
- A file that is not UTF-8 is refused.
- A second run on the result changes nothing.
26 files in src/, 7800 lines:
| Folder | Modules | Does |
|---|---|---|
src/ |
api, capi, cli, program, options, numbers |
the Rust API, the C interface, the program, numbers |
src/source/ |
absyn, tokens, lookup, resolve |
reads the source text, the Absyn tree and the library classes |
src/layout/ |
extract, diagram, placement, layered, grid, spring, ends, routing |
builds the diagram, places the components, routes the lines |
src/write/ |
annotate, graphics, svg |
writes the annotations and the SVG previews |
Names follow the rules of the Rust omc: snake_case
functions, CamelCase types, SCREAMING_SNAKE_CASE constants, rustfmt with max_width = 120,
errors as Result. src/numbers.rs has sind, cosd and the printing of numbers, so that
the output is the same to the last digit on every platform.
cargo testscripts/check.sh allcargo fmt -p mocoal -- --checkcargo clippy -p mocoal --all-targets --no-deps -- -D warnings57 tests, 0.3 s. Among them layouts in src/tests.rs: 14 cases on the 8 models
in test/models (a cascade control, an RC ladder, a resistor mesh, a drive train, a
chain of 24 gains, the rules of the layout, and the cases of the OpenModelica issues #7232 and
#16959), which use the parts in test/library/Parts.mo, not the MSL
(test/README.md gives the origin of each file). Each result must equal
its file in test/expected byte for byte: the Placement and Line coordinates.
On the laid-out diagram of each class it checks that no two components overlap, every line ends at
its ports, orthogonal lines are axis-aligned and pass through no component, and a second layout
changes nothing; with --keep, every Placement of the input stays as it was. After an intended
change of the layout:
MOCOAL_BLESS=1 cargo test -p mocoal layoutsthen review git diff test/expected.
check.sh [exe|lib|all] runs the program on
test/models/Chain.mo and compiles and runs interface/test_lib.c
against the library. cargo fmt and cargo clippy need -p mocoal (and clippy --no-deps):
without it they work on the fetched crates too.
scripts/compare.sh MOCOAL_A MOCOAL_B LIBRARY_DIR WORK_DIR [options] lays out a copy of a
library with two programs and compares the files, the SVG previews and the reports.
Modelica Standard Library 4.1.0, mocoal -i Modelica, macOS arm64: 2552 files in 1.1 to 1.5 s,
975 changed, 0 failed; 1182 classes, 8792 components placed, 9622 connections routed. A second
run changes 0 files.
The workflow .github/workflows/build.yml runs the checks, builds both forms and uploads them as artifacts: Linux x86_64 on a push or pull request; Linux, macOS arm64 and Windows x86_64 on a run by hand (Actions > Build > Run workflow) and for a release.
Only by hand: Actions > Release > Run workflow (.github/workflows/release.yml), with
commit: the commit to release, on master. Empty: the head of master.publish: make the tag and the release. Off (the default): a dry run, everything but those two.
The version comes from Cargo.toml of that commit. The workflow builds and tests that commit,
makes the tag v<version> on it and a GitHub release with:
mocoal-<platform>andlibmocoal-<platform>for Linux x86_64, macOS arm64 and Windows x86_64 (.tar.gz,.zipon Windows): the program or the library withREADME.mdand the licence files, built and tested as by the Build workflow;mocoal-rs-<version>-src.tar.gz: the complete source. The tree of the commit, the parser crates of OpenModelica and the crates.io dependencies (cargo vendor):cargo build --release --offlinebuilds it without network access (8 MB). GitHub's own "Source code" archives lack the parser crates;SHA256SUMSof all of them.
A version whose tag exists is refused: change the version in Cargo.toml first. A pushed tag
starts no release. A pull request that changes release.yml is a dry run. Nothing is published
to crates.io (publish = false).
- Components are not flipped, and only acausal parts are turned. A replaced
Placementloses its rotation and flip; the size of an existing extent is kept. Circuits with many parallel branches (ladders) come out worse than hand-made layouts: there are no junction points. - Modifiers and redeclarations are not applied in the class lookup.
- Connections to inherited components only choose the side the new components go to.
- With
--keep, existing lines are not obstacles for the new ones. replaceable ... constrainedby ... annotation(...): thePlacementgoes into the annotation of the constraining clause.
OSMC-PL 1.8 or AGPL v3, according to the recipient's choice. See LICENSE.md.

