Support multiple libraries and library versions

[AntoineGautier]

Context

The tool is hard-coded to only work with the Modelica Buildings Library, preventing use with other libraries.

This contrasts with the original requirements:

The template package of the Modelica Buildings Library is preloaded. The tool provides the option to load additional template packages from third-party libraries.

Library version management: If a loaded class contains the Modelica annotation uses (e.g., uses(Buildings(version="6.0.0")) the software checks the version number of the stored library. If the version number does not match, the tool simply alerts the user of version incompatibility.

Objective

This ticket is to provide support for multiple libraries, and multiple library versions.

A configuration file should enable specifying the libraries to be loaded and also support customized installations:

installation:
    name: "LBL-ctrl-flow"
    version: "1.0.0"
    maintainer: "LBL"
    description: "LBL maintained installation of ctrl-flow"

libraries:
    - name: "Buildings" # Only entry point libraries - other library dependencies will be detected through 'uses' annotations
      git_url: "https://github.com/lbl-srg/modelica-buildings.git" # Valid URL for git clone
      git_ref: "v11.0.0" # Optional branch, commit or tag to check out, otherwise the repo HEAD branch e.g. master is used
      exclude_packages:
        - "Buildings.Templates.Plants" # Modelica fully qualified package name to be excluded from install

The technical debt on isModelicaPath in client/src/interpreter/interpreter.ts can also be removed by relying on the library names specified in the configuration file.

To Do

The following needs to be refactored (non exhaustive list).

In https://github.com/lbl-srg/ctrl-flow-dev/blob/main/server/bin/install-modelica-dependencies.sh:

MODELICA_BUILDINGS_COMMIT=b399379315641da39b231033b0660100fd6489a5
...
git clone -b v3.2.3+build.4 --single-branch --depth 1 https://github.com/modelica/ModelicaStandardLibrary.git

• A configuration file should be created to specify the library names and tag or commit number to be loaded.

• The library dependencies (here Modelica Standard Library) should be identified based on the Modelica uses annotation from the libraries to be loaded, see Fetch MSL version from uses annotation #412.

  • [EDIT on 5/12/25] Further specification is needed regarding how to resolve a uses annotation such as uses(Modelica(version="4.0.0")) into a git URL.

In https://github.com/lbl-srg/ctrl-flow-dev/blob/main/server/Dockerfile:

ENV MODELICAPATH=/dependencies/ModelicaStandardLibrary:/dependencies/modelica-buildings
...
RUN node modelica-json/app.js -f modelica-buildings/Buildings/Templates -o json -d template-json

• The variable MODELICAPATH should be assigned a value based on the libraries specified in the configuration file and their dependencies.
• For each loaded library, the root package where templates are stored should be found based on the Modelica annotation __ctrlFlow(routing="root"), see Modify __ctrlFlow annotations for enhanced routing logic in the Templates package  modelica-buildings#4090.

In https://github.com/lbl-srg/ctrl-flow-dev/blob/main/server/scripts/parse-template-package.ts:

loadPackage("Buildings.Templates");

• See above for how to detect the root package where templates are stored.
• The templates should be parsed separately for each loaded library.

In https://github.com/lbl-srg/ctrl-flow-dev/tree/main/server/scripts/sequence-doc/src:

• The source documents to create the sequence documentation should be organized by {library, version}.
• The DEFAULT_DOC_VERSION variable should depend on {library, version}.

In the React frontend:

• The left navigation panel should be organized to display the tree-structure of the templates package for each loaded library.

├── Library 1
│   └── Air handlers and fans
│   └── Plants
└── Library 2
    └── Air handlers and fans
    └── Zone equipment

• The payload sent to the server to create the documentation should include the information about the library and version of the configured templates.

[mwetter]

@AntoineGautier : While we are working on adding this support, I wonder if we should also add some kind of a configuration. A use cases is that there are two ctrl-flow installations, say one is managed by LBL and one by CERL (or one is the stable release and one is a nightly release). Now, assume CERL does not want to include Zone equipment, perhaps because it has not reviewed them. How would ctrl-flow be configured to exclude the export of certain packages?

[AntoineGautier]

@mwetter Good point. What about the configuration file I propose in #431 (comment)?

[mwetter]

@AntoineGautier : The configuration looks good but this point could be considered: Now it has entries

      url: "https://github.com/lbl-srg/modelica-buildings.git"
      tag: "v11.0.0" # One of tag or commit must be specified
      commit: # One of tag or commit must be specified

This makes it cumbersome to use the head of a branch, such as for CI testing using the latest version of the library (or a branch). It also raises the issue of what happens if both, tag and commit are specified (probably an error).
An alternate specification could be a full url to the head, tag, branch, with valid entries being one of these:

   url: "https://github.com/lbl-srg/modelica-buildings/tree/v11.0.0"
   url: "https://github.com/lbl-srg/modelica-buildings/" # head of the master
   url: "https://github.com/lbl-srg/modelica-buildings/tree/issue4110_cdlInDHC"  # head of that branch
   url: "https://github.com/lbl-srg/modelica-buildings/commit/8712af7d680d5daa8a559e56f789346201306776"

[AntoineGautier]

I'm tracking here what remains to be done after #457 to support multiple Modelica libraries.

• Refactor the function isModelicaPath used in the client interpreter (should probably be done anyway considering how fragile the current implementation is)

  // This is a hack to determine modelica paths
  // The backend expands all relative paths every 'option' path should begin with 'Modelica'
  // 'Modelica' or 'Buildings' it is a modelica path
  function isModelicaPath(path: string) {
    return path.startsWith("Modelica") || path.startsWith("Buildings");
  }

• UI enhancements to support nested view and horizontal scrolling: templates and packages are still presented in a flat list (see screenshot below), both in the navigation pane and in the central pane.

• Solve the disconnect between loadPackage("Buildings.Templates") in server/scripts/parse-template-package.ts and findPackageEntryPoints() in server/src/parser/loader.ts. The root package name found by the latter function for each library should be exported and reused by server/scripts/parse-template-package.ts.

• Add annotation such as __ctrlFlow(description="MBL Templates")) that could override the class description. Users of the Buildings Library and users of ctrl-flow likely don't need the same description for the top-level package.

• Add a configuration file to specify the libraries that should be loaded during the build process, see example in Support multiple libraries and library versions #431 (comment).

• Rely on package.order to order the templates and packages: this requires Issue203 correct logical expression modelica-json#281