What Problem does this Solve?

Complex systems require complex models.

Imagine this scenario:

• Global automotive company Fred are designing a new model of their popular Mondo family saloon.
• A complex organisation are working on a range of models across the entire product hierarchy. Each team have their own Git repository containing their model files.
• The Vehicle Integration Team need to take models from several teams and build and test a full model of the Mondo.
• The Electric Battery Supercoolant Pump team have just developed a new design. The business wants to quickly evaluate its performance in a Vehicle Integration level simulation.
• However, the pump component is abstracted by several layers of product hierarchy from the Vehicle Integration level, and integrating these changes would create work at each of these layers, and cause a configuration control challenge as the pump is still on a model branch and has not been fully tested or reviewed.

The Model Assembly Language attempts to support large-scale modelling teams (or teams of teams) with challenges similar to this. It provides a simple, flexible and human-readable alternative to methods such as Git submodules for integrating many model dependencies of various baselines, whilst allowing appropriate rigour as the assembly instructions are plain-text and can be managed in configuration control.

What does this do?

• The Model Assembly Lanuage MAL is a structured language inspired by Helm for use with MATLAB.
• It enables a user to specify the dependencies for a project in a flexible yaml-based approach.
• Dependencies can cascade, allowing hierarchical expansion of a model structure.
• The MAL enables precise control of the configuration of model hierachy, including branch, tag, and commit referencing, including injection of a lower-level configuration.

Quick Guide

In your local project, specify a list of dependencies by writing an Instruction set mal.yaml as follows:

dependencies:
- type: git
  url: https://github.com/<MyOrganisation>/component-a.git

- type: git
  url: https://github.com/<MyOrganisation>/component-b.git
  branch: feature/new-gizmo

- type: git
  url: https://github.com/<MyOrganisation>/component-c.git
  tag: release/1.0.3

Then, fetch your dependencies using the following:

mal.fetchInstructionSet("mal.yaml")

The dependencies will then be checked-out into the submodules/<dependencyName> folder.

Requirements

• MATLAB
  • Developed using R2023a
  • Should work from R2020a (untested)
• Git
• yaml for MATLAB by Martin Koch

Detailed Guide

An Instruction set is a .yaml file. It can be in any project directory and have any name. When loaded, it will be translated into a mal.ModelAssemblyInstructions object.

Full example:

stagingDirectory: project/submodules

instructions:
- path: instructions/assembly.yaml
- path: instructions/config.yaml

dependencies:
- type: git
  name: componentA
  url: https://github.com/<MyOrganisation>/component-a.git

- type: git
  url: https://github.com/<MyOrganisation>/component-b.git
  branch: feature/new-gizmo

- type: git
  url: https://github.com/<MyOrganisation>/component-c.git
  tag: release/1.0.3

- type: git
  url: https://github.com/<MyOrganisation>/component-d.git
  instructions: sub-instructions.yaml

values:
- name: component-d.git
  value: 
  - name: component-e.git
    value: 
    - name: tag
      value: release/2.0.0.

It has the following fields:

Examples

See examples.

Contributing

Thanks for contributing! Please report bugs or raise a Pull Request to contribute.

License

MIT License