Add description fields for Implementation and Component

Author: LourensVeen

ymmsl/conversion/convert_v0_1_to_v0_2.py

@@ -31,13 +31,13 @@ def convert_v0_1_to_v0_2(config: v0_1.PartialConfiguration) -> v0_2.Configuratio
 
 def convert_component(component: v0_1.Component) -> v0_2.Component:
     """Convert a v0.1 Component object to a v0.2 Component."""
-    ports = component.ports if component.ports else v0_1.Ports()
+    ports = component.ports if component.ports else v0_2.Ports()
     implementation: Optional[str] = None
     if component.implementation is not None:
         implementation = str(component.implementation)
 
     return v0_2.Component(
-            str(component.name), ports, implementation, component.multiplicity)
+            str(component.name), ports, '', implementation, component.multiplicity)
 
 
 def convert_conduit(conduit: v0_1.Conduit) -> v0_2.Conduit:
@@ -56,10 +56,11 @@ def convert_model(model: v0_1.ModelReference) -> v0_2.Model:
     """
     if isinstance(model, v0_1.Model):
         return v0_2.Model(
-                str(model.name), None, list(map(convert_component, model.components)),
+                str(model.name), None, '',
+                list(map(convert_component, model.components)),
                 list(map(convert_conduit, model.conduits)))
     else:
-        return v0_2.Model(str(model.name), None, [], [])
+        return v0_2.Model(str(model.name), None, '', [], [])
 
 
 def convert_implementation(impl: v0_1.Implementation) -> v0_2.Program:
@@ -78,7 +79,7 @@ def convert_implementation(impl: v0_1.Implementation) -> v0_2.Program:
             'In yMMSL v0.2 implementations have become programs, and you can now'
             ' specify the ports of a program in the yMMSL description. If your program'
             ' has fixed ports then you should do this, because it will make incorrect'
-            ' wiring easier to debug.')
+            ' wiring easier to debug. While there, add a description too!')
 
     base_env: Optional[v0_1.BaseEnv] = impl.base_env
     env: Optional[Dict[str, str]] = impl.env
@@ -90,6 +91,6 @@ def convert_implementation(impl: v0_1.Implementation) -> v0_2.Program:
             env = None
 
     return v0_2.Program(
-                str(impl.name), None, base_env, impl.modules, impl.virtual_env, env,
+                str(impl.name), None, '', base_env, impl.modules, impl.virtual_env, env,
                 impl.execution_model, impl.executable, impl.args, impl.script,
                 impl.can_share_resources, impl.keeps_state_for_next_use)

ymmsl/v0_2/component.py

@@ -18,24 +18,28 @@ class Component:
     Attributes:
         name: The name of this component
         ports: The ports by which this component can be connected to others
+        description: A human-readable description of this component
         implementation: A Model or Program implementing this component
         multiplicity: The shape of the set of instances
     """
     def __init__(
             self, name: str, ports: Ports,
+            description: str,
             implementation: Optional[str] = None,
             multiplicity: Union[None, int, List[int]] = None) -> None:
         """Create a Component
 
         Args:
             name: The name of the component, must be a valid Identifier
+            description: Human-readable description of this component
             ports: Ports on this component that can be used to connect it
             implementation: The name of the implementation, must be a valid Reference
             multiplicity: The shape of the set of instances, or a number describing the
                 size of a 1D set of them, or None to have a single instance.
         """
         self.name = Identifier(name)
         self.ports = ports
+        self.description = description
 
         if implementation is not None:
             self.implementation: Optional[Reference] = Reference(implementation)

ymmsl/v0_2/implementation.py

@@ -17,12 +17,14 @@ class Implementation:
         ports: The ports this implementation has on which it sends and receives messages
     """
     def __init__(
-            self, name: str, ports: Optional[Ports] = None) -> None:
+            self, name: str, ports: Optional[Ports] = None,
+            description: str = 'Please add a description!') -> None:
         """Create an Implementation
 
         Args:
             name: Name of this implementation, must be a valid reference
             ports: The ports this implementation communicates on
+            description: Human-readable description of this implementation
         """
         if not isinstance(name, Reference):
             self.name = Reference(name)
@@ -33,3 +35,5 @@ def __init__(
             self.ports = Ports()
         else:
             self.ports = ports
+
+        self.description = description

ymmsl/v0_2/model.py

@@ -143,22 +143,25 @@ class Model(Implementation):
     Attributes:
         name: The name by which this simulation model is known to the system.
         ports: Ports through which this model can communicate with other models.
+        description: Human-readable description of the model.
         components: A list of components making up the model.
         conduits: A list of conduits connecting the components.
     """
     def __init__(
             self, name: str, ports: Optional[Ports] = None,
+            description: str = '',
             components: Optional[List[Component]] = None,
             conduits: Optional[Sequence[AnyConduit]] = None) -> None:
         """Create a Model.
 
         Args:
             name: Name of this model, must be a valid reference
             ports: Ports of this model
+            description: Human-readable description of the model
             components: A list of components making up the model
             conduits: A list of conduits connecting the components
         """
-        super().__init__(name, ports)
+        super().__init__(name, ports, description)
 
         if components is None:
             self.components = []

ymmsl/v0_2/program.py

@@ -46,6 +46,7 @@ class Program(Implementation):
     Attributes:
         name: Name of the program
         ports: Ports this program supports, if fixed
+        description: Human-readable description of this program
         base_env: Base environment to start from
         modules: HPC software modules to load
         virtual_env: Path to a virtual env to activate
@@ -63,6 +64,7 @@ def __init__(
             self,
             name: str,
             ports: Optional[Ports] = None,
+            description: str = '',
             base_env: Optional[BaseEnv] = None,
             modules: Union[str, List[str], None] = None,
             virtual_env: Optional[Path] = None,
@@ -89,6 +91,7 @@ def __init__(
         Args:
             name: Name of the program, must be a valid reference
             ports: Ports this program has
+            description: Human-readable description of this program
             base_env: Base environment to start from, defaults to clean
             modules: HPC software modules to load
             virtual_env: Path to a virtual env to activate
@@ -102,7 +105,7 @@ def __init__(
             keeps_state_for_next_use: Does this program keep state for the next
                 iteration of the reuse loop. See :class:`KeepsStateForNextUse`.
         """
-        super().__init__(name, ports)
+        super().__init__(name, ports, description)
 
         if script is not None:
             err_arg = []

ymmsl/v0_2/tests/conftest.py

@@ -78,6 +78,7 @@ def test_config5() -> Configuration:
                 'macro', Ports(
                     f_init='init', o_i=['out1', 'out2'], s=['in1', 'in2'],
                     o_f=['final']),
+                'description',
                 BaseEnv.LOGIN,
                 ['gcc/13.3.0', 'FFTW/3.2.1'],
                 Path('/home/user/.venv'),
@@ -110,6 +111,7 @@ def test_config5_text() -> str:
             '      - in2\n'
             '      o_f:\n'
             '      - final\n'
+            '    description: description\n'
             '    base_env: login\n'
             '    modules:\n'
             '    - gcc/13.3.0\n'
@@ -132,6 +134,7 @@ def test_config6() -> Configuration:
     model1 = Model(
             'resources_test',
             None,
+            'description',
             [
                 Component('singlethreaded', Ports(), 'a'),
                 Component('multithreaded', Ports(), 'b'),
@@ -141,6 +144,7 @@ def test_config6() -> Configuration:
     model2 = Model(
             'resources_test2',
             None,
+            'description',
             [
                 Component('mpi_cores1', Ports(), 'c'),
                 Component('mpi_cores2', Ports(), 'd'),
@@ -161,9 +165,12 @@ def test_config6() -> Configuration:
 
 @pytest.fixture
 def test_config7() -> Configuration:
-    model1 = Model('got_resources', None, [Component('singlethreaded', Ports(), 'a')])
+    model1 = Model(
+            'got_resources', None, 'description',
+            [Component('singlethreaded', Ports(), 'description', 'a')])
     model2 = Model(
-            'missing_resources', None, [Component('singlethreaded', Ports(), 'b')])
+            'missing_resources', None, 'description',
+            [Component('singlethreaded', Ports(), 'description', 'b')])
     resources = [ThreadedResReq(Ref('got_resources.singlethreaded'), 1)]
 
     return Configuration('test_config7', None, [model1, model2], None, None, resources)
@@ -173,24 +180,27 @@ def test_config7() -> Configuration:
 def test_config8() -> Configuration:
     model1 = Model(
             'implementations_test',
-            None,
+            None, 'description',
             [
-                Component('no_implementation', Ports(o_i=['out'], s=['in']), None),
                 Component(
-                    'impl_no_ports', Ports(f_init=['in'], o_f=['out']), 'no_ports'),
+                    'no_implementation', Ports(o_i=['out'], s=['in']), 'description',
+                    None),
+                Component(
+                    'impl_no_ports', Ports(f_init=['in'], o_f=['out']), 'description',
+                    'no_ports'),
             ])
 
     model2 = Model(
             'implementations_test2',
-            None,
+            None, 'description',
             [
                 Component(
                     'impl_with_ports', Ports(f_init=['in'], o_f=['out']), 'with_ports'),
             ])
 
     programs = [
             Program(
-                'no_ports', None,
+                'no_ports', None, 'description',
                 script='/home/user/models/bin/modela'),
             Program(
                 'with_ports',
@@ -212,21 +222,25 @@ def test_config8() -> Configuration:
 def test_config9() -> Configuration:
     model1 = Model(
             'implementations_test_broken',
-            None,
+            None, 'description',
             [
-                Component('no_implementation', Ports(o_i=['out'], s=['in']), None),
                 Component(
-                    'impl_ports_mismatch', Ports(f_init=['in'], o_f=['out']), 'ports1'),
+                    'no_implementation', Ports(o_i=['out'], s=['in']), 'description',
+                    None),
+                Component(
+                    'impl_ports_mismatch', Ports(f_init=['in'], o_f=['out']),
+                    'description', 'ports1'),
             ])
 
     model2 = Model(
             'implementations_test2',
-            None,
+            None, 'description',
             [
                 Component(
-                    'impl_also_wrong', Ports(o_i=['out'], s=['in']), 'ports2'),
+                    'impl_also_wrong', Ports(o_i=['out'], s=['in']), 'description',
+                    'ports2'),
                 Component(
-                    'impl_extra_ports', Ports(f_init=['in']), 'ports3'),
+                    'impl_extra_ports', Ports(f_init=['in']), 'description', 'ports3'),
             ])
 
     programs = [

ymmsl/v0_2/tests/test_component.py

@@ -4,12 +4,14 @@
 
 
 def test_component_declaration() -> None:
-    test_decl = Component('test', Ports(), 'ns.model')
+    test_decl = Component('test', Ports(), 'description', 'ns.model')
     assert isinstance(test_decl.name, Identifier)
     assert str(test_decl.name) == 'test'
 
     assert len(test_decl.ports.f_init) == 0
 
+    assert test_decl.description == 'description'
+
     assert isinstance(test_decl.implementation, Reference)
     assert str(test_decl.implementation) == 'ns.model'
 
@@ -18,39 +20,39 @@ def test_component_declaration() -> None:
 
 
 def test_component_multiplicity() -> None:
-    test_decl = Component('test', Ports(), 'ns.model', 10)
+    test_decl = Component('test', Ports(), 'description', 'ns.model', 10)
     assert isinstance(test_decl.name, Identifier)
     assert str(test_decl.name) == 'test'
     assert test_decl.multiplicity == [10]
     assert str(test_decl) == 'test[0:10]'
 
-    test_decl = Component('test', Ports(), 'ns2.model2', [1, 2])
+    test_decl = Component('test', Ports(), 'description', 'ns2.model2', [1, 2])
     assert isinstance(test_decl.name, Identifier)
     assert str(test_decl.name) == 'test'
     assert str(test_decl.implementation) == 'ns2.model2'
     assert test_decl.multiplicity == [1, 2]
     assert str(test_decl) == 'test[0:1][0:2]'
 
     with pytest.raises(ValueError):
-        test_decl = Component('test', Ports(), 'ns2.model2[1]')
+        test_decl = Component('test', Ports(), 'description', 'ns2.model2[1]')
 
 
 def test_component_instances() -> None:
     c1 = Component('test', Ports(), 'model')
     assert c1.instances() == [Reference('test')]
 
-    c2 = Component('test', Ports(), 'model', 3)
+    c2 = Component('test', Ports(), 'description', 'model', 3)
     assert c2.instances() == [
             Reference('test[0]'), Reference('test[1]'), Reference('test[2]')]
 
-    c3 = Component('test', Ports(), 'model', [2, 2])
+    c3 = Component('test', Ports(), 'description', 'model', [2, 2])
     assert c3.instances() == [
             Reference('test[0][0]'), Reference('test[0][1]'),
             Reference('test[1][0]'), Reference('test[1][1]')]
 
 
 def test_component_ports() -> None:
-    c = Component('test', Ports(['init'], ['out'], ['in'], ['final']))
+    c = Component('test', Ports(['init'], ['out'], ['in'], ['final']), 'description')
     assert isinstance(c.ports, Ports)
 
     assert c.ports.f_init == ['init']

ymmsl/v0_2/tests/test_configuration.py

@@ -17,11 +17,11 @@
 def test_configuration() -> None:
     setting_values: OrderedDict[str, SettingValue] = OrderedDict()
     settings = Settings(setting_values)
-    model1 = Model('model1', None, [])
-    model2 = Model('model2', None, [])
-    config = Configuration('testing', None, [model1, model2], settings)
+    model1 = Model('model1', None, 'description', [])
+    model2 = Model('model2', None, 'description', [])
+    config = Configuration('description', None, [model1, model2], settings)
 
-    assert config.description == 'testing'
+    assert config.description == 'description'
 
     assert len(config.models) == 2
     assert config.models[Ref('model1')] is model1
@@ -42,16 +42,19 @@ def test_load_models() -> None:
             '        ports:\n'
             '          o_i: out\n'
             '          s: in\n'
+            '        description: the macro component\n'
             '        implementation: macro_program\n'
             '      micro:\n'
             '        ports:\n'
             '          f_init: init\n'
             '          o_f: final\n'
+            '        description: the micro component\n'
             '        implementation: micro_program\n'
             '  do_nothing:\n'
             '    components:\n'
             '      nil:\n'
             '        ports: {}\n'
+            '        description: a component that does nothing\n'
             '        implementation: nil_program\n'
             )
 
@@ -198,23 +201,26 @@ def test_configuration_update_description() -> None:
 
 def test_configuration_update_model_error() -> None:
     base = Configuration(
-            'Configuration for testing', None, [Model('model', Ports(), [
-                Component('macro', Ports(o_i='out', s='in')),
-                Component('micro', Ports(f_init='init', o_f='final'))
+            'Configuration for testing', None, [Model('model', Ports(), 'description', [
+                Component('macro', Ports(o_i='out', s='in'), 'description'),
+                Component('micro', Ports(f_init='init', o_f='final'), 'description')
             ], [
                 Conduit('macro.out', 'micro.init'),
                 Conduit('micro.final', 'macro.in')]
             )])
 
     overlay1 = Configuration(
             'Extra component', None,
-            [Model('model', None, [Component('micro2', Ports())], [])])
+            [
+                Model('model', None, 'description',
+                      [Component('micro2', Ports(), 'description')], [])
+            ])
 
     with pytest.raises(RuntimeError):
         base.update(overlay1)
 
     overlay2 = Configuration(
-            'Extra conduit', None, [Model('model', None, [], [
+            'Extra conduit', None, [Model('model', None, 'description', [], [
                 Conduit('micro.final', 'macro.in2')])])
 
     with pytest.raises(RuntimeError):