|
| 1 | +Basic usage |
| 2 | +=========== |
| 3 | + |
| 4 | +A yMMSL file is a YAML file that looks approximately like this: |
| 5 | + |
| 6 | +.. literalinclude:: example_model.ymmsl |
| 7 | + :caption: ``docs/example_model.ymmsl`` |
| 8 | + :language: yaml |
| 9 | + |
| 10 | +yMMSL files can contain descriptions of multiscale and multiphysics coupled models (as |
| 11 | +above), settings to configure the models, programs to use to run them, and other |
| 12 | +information needed to run a simulation like compute resources to use and when to |
| 13 | +checkpoint. |
| 14 | + |
| 15 | +The yMMSL YAML format is supported by the ymmsl-python library, whose documentation you |
| 16 | +are currently reading. This library lets you read and write yMMSL files, and manipulate |
| 17 | +their contents using an object-based Python API. |
| 18 | + |
| 19 | +Installation |
| 20 | +------------ |
| 21 | + |
| 22 | +ymmsl-python is on PyPI, so you can install it using Pip: |
| 23 | + |
| 24 | +.. code-block:: bash |
| 25 | +
|
| 26 | + pip install ymmsl |
| 27 | +
|
| 28 | +or you can add it to your dependencies as usual, e.g. in your ``setup.py`` or your |
| 29 | +``pyproject.toml``, depending on how you've set up your project. |
| 30 | + |
| 31 | +Reading yMMSL files |
| 32 | +------------------- |
| 33 | + |
| 34 | +Here is an example of loading a yMMSL file: |
| 35 | + |
| 36 | +.. code-block:: python |
| 37 | +
|
| 38 | + from pathlib import Path |
| 39 | + import ymmsl |
| 40 | +
|
| 41 | + config = ymmsl.load(Path('docs/example_model.ymmsl')) |
| 42 | +
|
| 43 | +This makes ``config`` an object of type :class:`.ymmsl.v0_2.Configuration`, which is the |
| 44 | +top-level class describing a yMMSL document. More on these objects in the next section. |
| 45 | +The :func:`ymmsl.load` function can also load from an open file or from a string |
| 46 | +containing YAML data. |
| 47 | + |
| 48 | +If the file is not recognized as a yMMSL file, the library will raise a |
| 49 | +:class:`yatiml.RecognitionError` with a message describing in detail what is wrong, so |
| 50 | +that you can easily fix the file. |
| 51 | + |
| 52 | +Note that the :func:`ymmsl.load` function uses the safe loading functionality of the |
| 53 | +underlying YAML library, so that you can safely load files from untrusted sources. |
| 54 | + |
| 55 | +Writing yMMSL files |
| 56 | +------------------- |
| 57 | + |
| 58 | +To write a yMMSL file with the contents of a :class:`.ymmsl.v0_2.Configuration`, we use |
| 59 | +``ymmsl.save``: |
| 60 | + |
| 61 | +.. code-block:: python |
| 62 | +
|
| 63 | + from pathlib import Path |
| 64 | + from ymmsl.v0_2 import Component, Configuration, Model, Ports, Settings |
| 65 | + import ymmsl |
| 66 | +
|
| 67 | + model = Model( |
| 68 | + 'example_model', components=[Component('macro', Ports(), 'The macro model')]) |
| 69 | + settings = Settings({'example_parameter': 42}) |
| 70 | + config = Configuration(model, settings) |
| 71 | +
|
| 72 | + ymmsl.save(config, Path('out.ymmsl')) |
| 73 | +
|
| 74 | +Here, we create a model named ``example_model``, containing a single component named |
| 75 | +``macro``, and no conduits. For the settings, we create a Settings object, which is a |
| 76 | +container for a dictionary of settings. |
| 77 | + |
| 78 | +Finally, we combine the model and the settings into a :class:`.ymmsl.v0_2.Configuration` |
| 79 | +object, which we then save to a file. If you want to have the YAML as a string, use |
| 80 | +:func:`ymmsl.dump` instead. |
| 81 | + |
| 82 | +As the format develops over time, files are required to carry a version, in this case |
| 83 | +v0.2, which is currently the latest version of yMMSL. |
| 84 | + |
| 85 | +When you read in a yMMSL file as described above, you get a collection of Python |
| 86 | +objects describing its contents. The next section explains how those work. |
0 commit comments