Exchange formats

A model is useful to other disciplines only if they can read it. arclang export writes it in the formats their tools already use. Every export is deterministic: for one model and one version of the tool the output is byte-identical across runs and machines, so a difference in a generated file always means the model changed.

The examples use examples/features/timing-constraints/timing_constraints.arc, a lane keeping assistant.

Requirements: ReqIF

ReqIF 1.0 is the exchange format of requirements tools such as DOORS, Polarion and Jama.

$ arclang export examples/features/timing-constraints/timing_constraints.arc -f req-if -o lka.reqif
Exporting examples/features/timing-constraints/timing_constraints.arc to ReqIF format...
✓ Export successful
  Input: examples/features/timing-constraints/timing_constraints.arc
  Output: lka.reqif
  Format: ReqIF
warning: ReqIF carries requirements only: 2 trace(s) between a requirement and another element left out (satisfies: 2)

The export validates against the OMG ReqIF schema. Identifiers are derived from the model, so exporting twice gives the same file and a requirements tool sees an update, not new objects; a requirement that came from a requirements tool keeps the identifier it had there (reqif_id), so the loop with DOORS or Polarion updates its objects instead of duplicating them. Relations between requirements are exported, and so are their other attributes, as text. ReqIF carries requirements only: a trace from a requirement to an architecture element is not exported, and the export says how many and of which kinds.

arclang import -f req-if reads a ReqIF file from another tool. Each specification becomes a requirements block of its name; the hierarchy of the specification becomes parent:; relations become refines traces, with their ReqIF type; XHTML text, enumeration values and the standard attributes (ReqIF.ForeignID, ReqIF.ChapterName, ReqIF.Text, ReqIF.Name) are read, and the foreign identifier is kept as reqif_id. It is tested on files written by DOORS, Polarion, ReqIF Studio and Eclipse RMF.

Simulation: Simulink and System Composer

$ arclang export examples/features/timing-constraints/timing_constraints.arc -f simulink -o lka.m
Exporting examples/features/timing-constraints/timing_constraints.arc to Simulink format...
✓ Export successful
  Input: examples/features/timing-constraints/timing_constraints.arc
  Output: lka.m
  Format: Simulink

The result is a MATLAB script that rebuilds the architecture in System Composer, with the calls MathWorks documents: the logical components with their hierarchy, their oriented ports and a port-to-port connection per exchange; the physical architecture as a second model, its nodes, ports and links; and a Stateflow chart per state machine, with its default transition (guards that are not Stateflow action language go in the transition's description). Names are made valid and unique per level, and the script is deterministic. The script is generated and statically checked, not run in MATLAB by our tests.

$ sed -n '9,20p' lka.m

%% Components
c_LC_CAM = addComponent(arch, 'Camera');
c_LC_CTL = addComponent(arch, 'LKA Controller');

%% Ports
addPort(c_LC_CAM.Architecture, 'lane', 'out');
addPort(c_LC_CTL.Architecture, 'lane', 'in');

%% Connections
connect(c_LC_CAM.getPort('lane'), c_LC_CTL.getPort('lane')); % LaneFlow

Co-simulation: FMI 2.0

$ arclang export examples/features/timing-constraints/timing_constraints.arc -f fmi -o fmi
Exporting examples/features/timing-constraints/timing_constraints.arc to FMI format...
  ✓ Camera (LC-CAM) -> fmi/LC-CAM/modelDescription.xml
  ✓ LKA Controller (LC-CTL) -> fmi/LC-CTL/modelDescription.xml
✓ Export successful — 2 FMU interface(s)
  Input: examples/features/timing-constraints/timing_constraints.arc
  Output directory: fmi

One modelDescription.xml per component: the interface an FMU of that component must have, without its binaries, for the simulation team to implement and for an importer to check against. Each port is one variable, typed by what it carries; its causality comes from its direction, and an inout port gives an input and an output (name_in, name_out), FMI 2.0 having no bidirectional variable. Every file validates against the FMI 2.0.4 schema and passes fmpy's FMU validation. The GUID is derived from the model, the component and its interface: it survives regeneration, and changes when the interface changes, so a stale FMU is not taken for a current one.

$ cat fmi/LC-CAM/modelDescription.xml
<?xml version="1.0" encoding="UTF-8"?>
<fmiModelDescription fmiVersion="2.0" modelName="Camera" guid="{1bc46b15-30d1-52b7-b540-19b0c33ea0d3}" generationTool="ArcLang" numberOfEventIndicators="0">
  <CoSimulation modelIdentifier="LC_CAM" canHandleVariableCommunicationStepSize="true"/>
  <ModelVariables>
    <ScalarVariable name="lane" valueReference="0" causality="output" variability="continuous" initial="calculated">
      <Real/>
    </ScalarVariable>
  </ModelVariables>
  <ModelStructure>
    <Outputs>
      <Unknown index="1"/>
    </Outputs>
    <InitialUnknowns>
      <Unknown index="1"/>
    </InitialUnknowns>
  </ModelStructure>
</fmiModelDescription>

Software: C headers and Protobuf

The interface contracts of the logical architecture can be generated for the software teams.

$ arclang export examples/features/timing-constraints/timing_constraints.arc -f c-headers -o lka_interfaces.h
Exporting examples/features/timing-constraints/timing_constraints.arc to CHeaders format...
✓ Export successful
  Input: examples/features/timing-constraints/timing_constraints.arc
  Output: lka_interfaces.h
  Format: CHeaders

$ sed -n '14,22p' lka_interfaces.h

/* ---- Camera (LC-CAM) ---- */
/* port out lane — provided by the integration layer */
void lc_cam_send_lane(const void *payload, size_t payload_len);

/* ---- LKA Controller (LC-CTL) ---- */
/* port in lane — implement this handler */
void lc_ctl_on_lane(const void *payload, size_t payload_len);

$ arclang export examples/features/timing-constraints/timing_constraints.arc -f proto -o lka.proto
Exporting examples/features/timing-constraints/timing_constraints.arc to Proto format...
✓ Export successful
  Input: examples/features/timing-constraints/timing_constraints.arc
  Output: lka.proto
  Format: Proto

$ sed -n '3,12p' lka.proto
syntax = "proto3";

package lane_keeping_timing;

message Ack {}

service CameraService {
  rpc LaneFlow(Ack) returns (Ack);
}

In every case ArcLang generates contracts only: the shape of the interfaces, never the behavior. Behavior stays in the simulation tool or in the code.

Systems modeling: SysML v2 and Capella

• -f sys-ml writes SysML v2 textual notation, validated by the OMG pilot implementation. See SysML v2.
• Capella models go through the bridge. See Capella.

Physics: Modelica and OpenModelica

-f modelica writes the physical architecture as a Modelica package, to be extended by hand-written physics and simulated in OpenModelica. Ports that declare physics: become Modelica Standard Library connectors, links become connect equations. From 4.6 the export also draws the architecture with Placement and Line annotations so Modex and OMEdit can display it. See Simulation.

Model data: JSON

-f json writes the parsed model as JSON, for scripts and for the Capella bridge. The HTTP API serves the compiled model with stable UUIDs.

$ arclang export examples/features/timing-constraints/timing_constraints.arc -f json -o lka.json
Exporting examples/features/timing-constraints/timing_constraints.arc to JSON format...
✓ Export successful
  Input: examples/features/timing-constraints/timing_constraints.arc
  Output: lka.json
  Format: JSON

Documents and diagrams

-f html writes the architecture document with its diagrams, and arclang diagram the viewer alone. See Diagrams. -f markdown, -f mermaid and -f plant-uml write text for documentation pipelines.