Merge pull request #52 from iterorganization/feature/muscle3-actor

Muscle3 actor

Author: maarten-ic

docs/source/index.rst

@@ -21,6 +21,7 @@ Manual
    cli
    tendencies
    yaml_format
+   muscle3
 
 .. toctree::
    :caption: API docs

docs/source/muscle3.rst

@@ -0,0 +1,77 @@
+MUSCLE3 IMAS Actor
+==================
+
+The waveform editor includes an actor that can be included in an IMAS `MUSCLE3
+<https://muscle3.readthedocs.io/>`__ simulation.
+
+.. caution::
+    The IMAS MUSCLE3 actor requires the following packages:
+
+    - `muscle3 <https://pypi.org/project/muscle3>`__
+    - `imas_core <https://git.iter.org/projects/IMAS/repos/al-core/browse>`__ which is
+      not (yet) publicly available.
+
+
+This page assumes you are familiar with MUSCLE3 and IMAS coupled simulations.
+
+
+Actor details
+-------------
+
+The actor expects messages on a single input port. We take the timestamp of the
+message and evaluate all waveforms at that moment in time. These waveforms are
+stored in their respective IDSs and sent on the respective (connected) output port.
+
+.. code-block:: yaml
+    :caption: Example ``implementations`` section for running the waveform-editor actor
+
+    implementations:
+      waveform_actor:
+        executable: waveform-editor
+        args: actor
+
+Available settings
+''''''''''''''''''
+
+- ``waveforms`` (mandatory): indicate the (full) path to the waveform configuration.
+
+
+Input ports (``F_INIT``)
+''''''''''''''''''''''''
+
+The actor has one input port. The name can be chosen freely in the workflow yMMSL (see
+example below).
+
+The actor will stop with a ``RuntimeError`` when there are no input ports, or when there
+are multiple input ports declared.
+
+
+Output ports (``O_F``)
+'''''''''''''''''''''''
+
+The actor can have one output port per IDS that is defined in the waveform
+configuration. Output ports must be named ``<ids_name>_out`` or ``<ids_name>``.
+
+The actor will stop with a ``RuntimeError`` when an output port is connected for which
+there is no corresponding waveform defined. For below example, the actor would report an
+error when the ``waveforms.yaml`` doesn't contain waveforms for either the
+``ec_launchers`` IDS or the ``nbi`` IDS.
+
+
+Example
+-------
+
+The following yMMSL shows an example coupling for a hypothetical ``controller`` actor
+with the waveform-editor actor. N.B. ``__PATH__`` is a placeholder which should be
+replaced with the full path to the files.
+
+.. literalinclude:: ../../tests/muscle3_integration/coupling.ymmsl.in
+    :language: yaml
+    :caption: coupling.ymmsl.in
+
+The corresponding waveform configuration is shown below:
+
+.. literalinclude:: ../../tests/muscle3_integration/waveforms.yaml
+    :language: yaml
+    :caption: waveforms.yaml
+

pyproject.toml

@@ -29,7 +29,10 @@ dependencies = [
 dynamic = ["version"]
 
 [project.optional-dependencies]
-all = ["waveform-editor[dev,linting,test,docs]"]
+all = ["waveform-editor[muscle3,dev,linting,test,docs]"]
+muscle3 = [
+    "muscle3",
+]
 dev = [
     "waveform-editor[test,linting]",
     # useful to run panel in --dev mode

tests/muscle3_integration/.gitignore

@@ -0,0 +1 @@
+coupling.ymmsl

tests/muscle3_integration/controller.py

@@ -0,0 +1,38 @@
+import imas
+import numpy as np
+from libmuscle import Instance, Message
+from ymmsl import Operator
+
+
+def controller():
+    """Dummy controller actor for demonstrating the waveform actor."""
+    instance = Instance(
+        ports={
+            Operator.O_I: ["time_out"],
+            Operator.S: ["ec_launchers_in", "nbi_in"],
+        }
+    )
+
+    factory = imas.IDSFactory("4.0.0")
+
+    while instance.reuse_instance():
+        for time in np.linspace(0, 50, 20):
+            # The data of this message is ignored by the waveform-actor, only the
+            # timestamp is relevant:
+            instance.send("time_out", Message(time))
+
+            # Receive waveform input
+            msg = instance.receive("ec_launchers_in")
+            ec_launchers = factory.new("ec_launchers")
+            ec_launchers.deserialize(msg.data)
+
+            msg = instance.receive("nbi_in")
+            nbi = factory.new("nbi")
+            nbi.deserialize(msg.data)
+
+            # An actual actor would do something with the received data now:
+            ...
+
+
+if __name__ == "__main__":
+    controller()

tests/muscle3_integration/coupling.ymmsl.in

@@ -0,0 +1,47 @@
+ymmsl_version: v0.1
+
+model:
+  name: example_coupling_with_waveform_actor
+
+  components:
+    controller:
+      implementation: controller
+      ports:
+        o_i: time_out
+        s:
+        - ec_launchers_in
+        - nbi_in
+      
+    waveform_actor:
+      implementation: waveform_actor
+      ports:
+        # The name of the input port can be freely chosen:
+        f_init: time_in
+        # Names of the output port are "<ids_name>_out":
+        o_f:
+        - ec_launchers_out
+        - nbi_out
+    
+  conduits:
+    controller.time_out: waveform_actor.time_in
+    waveform_actor.ec_launchers_out: controller.ec_launchers_in
+    waveform_actor.nbi_out: controller.nbi_in
+
+settings:
+  # Mandatory setting for the waveform actor: the waveform configuration:
+  waveform_actor.waveforms: __PATH__/waveforms.yaml
+
+resources:
+  controller:
+    threads: 1
+  waveform_actor:
+    threads: 1
+
+implementations:
+  controller:
+    executable: python
+    args: __PATH__/controller.py
+  
+  waveform_actor:
+    executable: waveform-editor
+    args: actor

tests/muscle3_integration/test_muscle3_integration.py

@@ -0,0 +1,22 @@
+import subprocess
+from pathlib import Path
+
+import pytest
+
+pytest.importorskip("libmuscle")
+pytest.importorskip("imas_core")
+
+
+def test_muscle3_integration(tmp_path, monkeypatch):
+    # Prepare yMMSL file:
+    curpath = Path(__file__).parent
+    ymmsl_in = curpath / "coupling.ymmsl.in"
+    ymmsl_out = curpath / "coupling.ymmsl"
+    ymmsl_out.write_text(ymmsl_in.read_text().replace("__PATH__", str(curpath)))
+
+    # Start workflow and check that it completes successfully
+    subprocess.run(
+        ["muscle_manager", "--start-all", str(ymmsl_out)],
+        cwd=tmp_path,
+        check=True,
+    )

tests/muscle3_integration/waveforms.yaml

@@ -0,0 +1,19 @@
+# Very simple waveform configuration as an example for the MUSCLE3 IMAS actor
+globals:
+  dd_version: 4.0.0
+
+ec_launchers:
+  ec_launchers/beam(1)/power_launched/data:
+    # Ramp up to 50 kW
+    - {type: linear, to: 50e3, duration: 10}
+    # Flat top, constant at 50 kW
+    - {type: constant, duration: 30}
+    # Ramp down
+    - {type: linear, to: 0, duration: 10}
+
+nbi:
+  # Note that the actor would give an error if we do not include this waveform:
+  # the yMMSL file expects an output for the NBI IDS, so we must define
+  # waveforms for this IDS.
+  nbi/unit(1)/power_launched/data:
+  - {type: constant, value: 0}  # NBI is turned off for this configuration

tests/test_muscle3.py

@@ -0,0 +1,100 @@
+import imas
+import numpy as np
+import pytest
+
+# libmuscle and ymmsl are optional dependencies, so may not be installed
+libmuscle = pytest.importorskip("libmuscle")
+ymmsl = pytest.importorskip("ymmsl")
+
+# This cannot be imported if libmuscle is not available
+from waveform_editor.muscle3 import waveform_actor  # noqa: E402
+
+# imas_core is required for IDS serialize, unfortunately this means we cannot run these
+# tests in github Actions yet..
+pytest.importorskip("imas_core")
+
+
+WAVEFORM_YAML = """
+ec_launchers:
+  beams:
+    ec_launchers/beam(1)/phase/angle: 1
+    ec_launchers/beam(2)/phase/angle: 2
+    ec_launchers/beam(3)/phase/angle: 3
+    ec_launchers/beam(4)/power_launched/data:
+        - {to: 8.33e5, duration: 20}
+        - {type: constant, duration: 20}
+        - {duration: 25, to: 0}
+globals:
+  dd_version: 4.0.0
+"""
+TIMES = [1, 21, 50]
+VALUES_PER_TIME = [8.33e5 / 20, 8.33e5, 8.33e5 * 15 / 25]
+
+YMMSL = """
+ymmsl_version: v0.1
+
+model:
+  name: test_waveform_actor
+
+  components:
+    time_generator:
+      implementation: time_generator
+    waveform_actor:
+      implementation: waveform_actor
+    waveform_validator:
+      implementation: waveform_validator
+
+  conduits:
+    time_generator.output: waveform_actor.input
+    waveform_actor.ec_launchers_out: waveform_validator.ec_launchers_in
+
+settings:
+  waveform_actor.waveforms: {waveform_yaml}
+"""
+
+
+def time_generator():
+    instance = libmuscle.Instance({ymmsl.Operator.O_I: ["output"]})
+
+    while instance.reuse_instance():
+        for t in TIMES:
+            instance.send("output", libmuscle.Message(t))
+
+
+def waveform_validator():
+    instance = libmuscle.Instance({ymmsl.Operator.F_INIT: ["ec_launchers_in"]})
+
+    i = 0
+    while instance.reuse_instance():
+        msg = instance.receive("ec_launchers_in")
+        assert msg.timestamp == TIMES[i]
+
+        ids = imas.IDSFactory("4.0.0").ec_launchers()
+        ids.deserialize(msg.data)
+
+        assert np.array_equal(ids.time, [TIMES[i]])
+        assert len(ids.beam) == 4
+        assert np.array_equal(ids.beam[0].phase.angle, [1])
+        assert np.array_equal(ids.beam[1].phase.angle, [2])
+        assert np.array_equal(ids.beam[2].phase.angle, [3])
+        assert np.allclose(ids.beam[3].power_launched.data, [VALUES_PER_TIME[i]])
+
+        i += 1
+    assert i == len(TIMES)
+
+
+# Running `os.fork()` after `import pandas` triggers this warning...
+# It doesn't seem to be an issue (and not relevant in production where muscle_manager
+# will start the actor in a standalone process), so we'll ignore this warning:
+@pytest.mark.filterwarnings("ignore:.*use of fork():DeprecationWarning")
+def test_muscle3(tmp_path, monkeypatch):
+    monkeypatch.chdir(tmp_path)
+    waveform_yaml = (tmp_path / "waveform.yml").resolve()
+    waveform_yaml.write_text(WAVEFORM_YAML)
+    configuration = ymmsl.load(YMMSL.format(waveform_yaml=waveform_yaml))
+    implementations = {
+        "time_generator": time_generator,
+        "waveform_actor": waveform_actor,
+        "waveform_validator": waveform_validator,
+    }
+    libmuscle.runner.run_simulation(configuration, implementations)