Model Assembly Language

A structured language for managing complex hierarchical project dependencies.

7 Downloads

Updated 6 Apr 2023

From GitHub

View License on GitHub

Model Assembly Language

The ProblemFeaturesQuick GuideRequirementsDetailed GuideExamplesContributingLicense

View on File Exchange MIT License language Latest Release Tests codecov


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


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:

Attribute Description
stagingDirectory Relative directory where the dependencies will be located. Default is submodules. Individual dependencies will be located in a subfolder name matching their name.
instructions List additional instruction sets of ModelAssemblyInstructions to be read. These can specify additional instructions, dependencies, or values. This allows modular construction of instruction sets, reusing existing patterns and structures but with different configurations to suit various purposes.
instructions[].path Path to the additional instructions file.
dependencies List of individual dependencies, with the following attributes:
dependencies[].type Must be git. To enable future support of other types of repositories.
dependencies[].name Name of the dependency. If not set, this will be inherited from final element of the URL.
dependencies[].url URL of the dependency repository.
dependencies[].tag | .commit | .branch Specify a particular point in the repository to checkout, by either a specific tag, commit, or branch (in that order of preference). If a branch is specified, it will be checked out at the current HEAD. If nothing is specified, the default branch will be checked out at the current HEAD.
dependencies[].instructions Specify a ModelAssemblyInstructions within the dependency to continue a hierarchical build.
values List to allows overwrite of variables within an instruction set at any level of hierarchy.
values[].name Specify the name of the attribute to be overwritten. Can refer to an actual attribute, or the name of a dependency.
values[].value Specify the value of the attribute. If name is the name of a dependency, this is expected to be another name-value pair which will be applied to that dependency.

Examples

See examples.


Contributing

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

License

MIT License

Cite As

Ciaran McAndrew (2023). Model Assembly Language (https://github.com/CiaranMcAndrew/model-assembly-language/releases/tag/v1.0.2), GitHub. Retrieved .

MATLAB Release Compatibility
Created with R2023a
Compatible with any release
Platform Compatibility
Windows macOS Linux
Tags Add Tags

Community Treasure Hunt

Find the treasures in MATLAB Central and discover how the community can help you!

Start Hunting!

examples/example-a-basic-usage

examples/example-b-sub-instructions

examples/example-c-values

Version Published Release Notes
1.0.2.0

See release notes for this release on GitHub: https://github.com/CiaranMcAndrew/model-assembly-language/releases/tag/v1.0.2

1.0.1

See release notes for this release on GitHub: https://github.com/CiaranMcAndrew/model-assembly-language/releases/tag/v1.0.1

1.0.0

To view or report issues in this GitHub add-on, visit the GitHub Repository.
To view or report issues in this GitHub add-on, visit the GitHub Repository.