Example component

• Component description
• Development steps
• Running test simulation

Component description

The implemented component type is named SimpleComponent.

• The component takes three parameters as input when the component starts
  • SimpleValue, required float value, which is used to determine the value used in the output messages.
  • InputComponents, optional string value, which contains a comma-separated list of the other component names that provide input for this component. All the listed components are assumed to be other simple components. The default value is empty string, i.e. no components providing input.
  • OutputDelay, optional float value, which tells how many seconds to delay sending the output message after receiving all required input. The default value is 0.0, i.e. no delay.
• During each epoch, the component first waits input from other simple components and then sends an output message.

  • For the input and output messages, a new message type, Simple message, is used. It contains the AbstractResultMessage attributes with an additional SimpleValue attribute that contains a float value.

  • If the InputComponents list is empty, the output message is immediately send after receiving a new Epoch message (with the possible delay according to OutputDelay). Otherwise the output message is send after receiving all the required input messages.

  • The actual value for the attribute SimpleValue in the output message is determined by the following formula:

    if <inputComponents list is not empty>:
        SimpleValue = <sum of the SimpleValues received from all input messages> +
                      <the SimpleValue given to the component at startup>
    else:
        SimpleValue = <the SimpleValue given to the component at startup> +
                      <epoch number divided by 1000>
    

  • The output message is sent to topic SimpleTopic.<component_name>.

  • The Status ready message is sent immediately after the output message.

Development steps

This section documents the development steps taken during the development of this example component. Note, that there are no unit tests implemented for this example component. Also, some of the function descriptions are still incomplete.

1. Create a Git repository at GitHub under the simcesplatform organization.

   • from https://github.com/simcesplatform select "New"
   • for a new project, select "Initialize repository with a README"

2. Clone the Git repository locally.

   • from the platform installation folder

     git clone https://github.com/simcesplatform/Simple-Component.git
     # or if you are using SSH keys with GitHub
     git clone git@github.com:simcesplatform/Simple-Component.git

     where Simple-Component is the name of this repository

3. Initialize the submodule for simulation-tools library to utilize the Python library simulation-tools.

   # fetch and setup the library as a submodule
   git submodule add -b master https://github.com/simcesplatform/simulation-tools.git
   git submodule init
   git submodule update --remote --recursive
   
   # prepare the path for the submodule (to use tools.??? instead of simulation_tools.tools.???)
   cp -r simulation-tools/init .
   mkdir -p simple_component
   printf '"""Add submodules to the python path."""\n\nimport init\n' > simple_component/__init__.py

4. Create the message class, simple_component/simple_message.py, based on the message template from message_template.txt.

5. Create the component code, simple_component/simple_component.py, based on the component template from component_template.py.

6. Create the Dockerfile, Dockerfile, based on the Dockerfile template from Dockerfile-template.

7. Include the required Python libraries file, requirements.txt, based on the template file requirements.txt.

8. Create this readme file with a descriptions about the new component and its workflow. For actual component create also a documentation page for the component.

9. Create a configuration file for a test simulation that contains the newly created component.

   • The created test simulation configuration file for this simple component, simple_simulation.yml, contains four components that work similarly as the components on the documentation page Time and synchronization with epochs

10. Build and push a Docker image to the Container registry following the relevant instructions. (TODO: add the actual instructions here)

11. Test the component by running a test simulation.

Running test simulation

TODO: add steps to follow to install the platform and to run the simple component test simulation based on the general instructions.