Basic usage

A yMMSL file is a YAML file that looks approximately like this:

docs/example_model.ymmsl

ymmsl_version: v0.2

description: |
  # Example yMMSL file containing a model

  Note that many of these are optional, but they're all used here to show what the
  format is capable of.

models:
  macro_micro_model:
    description: |
      # A basic macro-micro (time-scale separation) reaction-diffusion model

      This model has two submodels, named macro and micro, that simulate the slow and
      fast dynamics respectively.

    supported_settings:
      domain_grain: float   Spatial distance between grid cells (m)
      domain_extent: float  Size of the domain (m)
      timestep: float       Step to take while integrating time (s)
      total_time: float     Total time to simulate for (s)
      k: float              Reaction coefficient
      d: float              Diffusion coefficient

    components:
      macro:
        ports:
          o_i: state_out
          s: update_in

        description: |
          # Macro (sub)model

          The macro (slow) model calls the micro model at each timestep

          ## Ports

          - state_out: 1D array of float
            Outputs the state at every time step

          - update_in: 1D array of float
            Receives a state update at every time step

        implementation: macro_model_program

      micro:
        ports:
          f_init: init_in
          o_f: final_out

        description: |
          # Micro model

          The micro (fast) (sub)model runs repeatedly

          ## Ports

          - init_in: 1D array of float
            Receives the system state on every run

          - final_out: 1D array of float
            Outputs a state update on every run

        implementation: micro_model_program

    conduits:
      macro.state_out: micro.init_in
      micro.final_out: macro.update_in

yMMSL files can contain descriptions of multiscale and multiphysics coupled models (as above), settings to configure the models, programs to use to run them, and other information needed to run a simulation like compute resources to use and when to checkpoint.

The yMMSL YAML format is supported by the ymmsl-python library, whose documentation you are currently reading. This library lets you read and write yMMSL files, and manipulate their contents using an object-based Python API.

Installation

ymmsl-python is on PyPI, so you can install it using Pip:

pip install ymmsl

or you can add it to your dependencies as usual, e.g. in your setup.py or your pyproject.toml, depending on how you’ve set up your project.

Reading yMMSL files

Here is an example of loading a yMMSL file:

from pathlib import Path
import ymmsl

config = ymmsl.load(Path('docs/example_model.ymmsl'))

This makes config an object of type ymmsl.v0_2.Configuration, which is the top-level class describing a yMMSL document. More on these objects in the next section. The ymmsl.load() function can also load from an open file or from a string containing YAML data.

If the file is not recognized as a yMMSL file, the library will raise a yatiml.RecognitionError with a message describing in detail what is wrong, so that you can easily fix the file.

Note that the ymmsl.load() function uses the safe loading functionality of the underlying YAML library, so that you can safely load files from untrusted sources.

Writing yMMSL files

To write a yMMSL file with the contents of a ymmsl.v0_2.Configuration, we use ymmsl.save:

from pathlib import Path
from ymmsl.v0_2 import Component, Configuration, Model, Ports, Settings
import ymmsl

model = Model(
    'example_model', components=[Component('macro', Ports(), 'The macro model')])
settings = Settings({'example_parameter': 42})
config = Configuration(model, settings)

ymmsl.save(config, Path('out.ymmsl'))

Here, we create a model named example_model, containing a single component named macro, and no conduits. For the settings, we create a Settings object, which is a container for a dictionary of settings.

Finally, we combine the model and the settings into a ymmsl.v0_2.Configuration object, which we then save to a file. If you want to have the YAML as a string, use ymmsl.dump() instead.

As the format develops over time, files are required to carry a version, in this case v0.2, which is currently the latest version of yMMSL.

When you read in a yMMSL file as described above, you get a collection of Python objects describing its contents. The next section explains how those work.