`oedisi` CLI¶

In oedisi.tools, there is a cli tool called oedisi. There are tools to build, run, and debug simulations as well as test component description JSONs.

Occasionally, the HELICS runner will fail to start and may need to be killed. The same may happen to the mock component used for testing.

A component-dict will be a JSON file with names to component definitions:

{
  "ComponentOne": "component1/component_definition.json",
  "ComponentTwo": "component2/component_definition.json"
}

Example Usage¶

Assuming we have our component dictionary components.json, the system JSON at system.json, and we want to build to build, then most command line parameters will not be necessary.

Build and run:

oedisi build
oedisi run

Multi-Container REST API endpoint requirements¶

Endpoint	Type	Usage	Reqired by
/	GET	Heath check. Returns hostname and ip	All containers
/profiles	POST	Enables upload of user defined profiles to the container	Broker federate + simulator federate (feeder federate in sigdal example)
/model	POST	Enables upload of user defined distribution model to the feeder container. Upload requires a zipped distribution model	Broker federate + simulator federate
/results	GET	Enables users to fetch results from all the recorder federates	Broker federate
/terminate	GET	Closes the HELICS library and ternimates the co-simulation	Broker federate only (co-simulation orchestrator)
/run	POST	Starts federate simulaton allowing to enter HELICS execution mode	All containers
/sensor	GET	Enables retrieval of available sensors	Simulator federate only
/download	GET	Enables users to fetch results from a recorder federate	Recorder federates only

Multi-Container Model Setup¶

The oedisi frameworks enables users to set up models as single-container (all models running in a single Docker container) or multi-container implementation (all componenets running in seperate docker containers.). The framework currently supports both Docker-compose and kubernetes configurations. By default, the oedisi frameworks sets up the single-container simulation. -m flag can be used to build additional files needed for either Docker-compose or Kubernetes orchestration.

Uploading user defined models requires setting the ‘user_uploads_model’ to true. If the flag is set to false, the model will be downloaded automatically from AWS.

Building files for multi-container implementation:

oedisi build -m

Once the build process is complete, the containers can be launched by either Docker-compose (all images will run on the local machine) or using Kubernetes (enables orchestration across multiple machines). Navigate to the build folder and execute following command to lauch all images in the build folder.

Running containers using Docker-compose:

docker compose up

Stopping containers using Docker-compose:

docker compose down

Alternately, Kubernetes setup files can be used to orchestrate the launch of all the required containers. Kubernetes deploment files are generated within the kubernetes folder inside the build folder. All files can be deployed using a file command (Both deployment and service files). It is to be noted that these files can be modified to serve a unique usecases.

Running containers using Kubernetes:

kubectl apply -f kubernetes

To access the REST API endpoint of the broker container, port forwarding can be used to expose the container port to the local machine. The command below forwards port 8766 of the broker container to port 8080 on the local machine.

kubectl port-forward service/oedisi-service 8080:8766

The REST API endpoint can then be accessed at http://localhost:8080

By default, the deployment file is configured to download required images from Docker Hub. Users have to option to modify the deployment file and use a local registery (https://docs.docker.com/registry/) to use local images instead.

Multi-Container Model Run¶

Once all required docker images are running (see last section), simulation run can be orchestration using the REST API interface. The interface aloows users to

Upload private data (distribution models and associated profiles)
Launch the simulation
Retrieve simulation results

IPs for containers and corresponding exposed ports are available to users within the docker-compose.yml file in the main build folder. To check healh of the API server the runnig container, user can open a web browser and browse to http://{ip}:{port}, where ip and port are container specific (see docker-compose.yml).

Identify the ip and port information for oedisi_broker container from the docker-compose.yml file.

Upload private data¶

Distribution models, compressed in zip format can be uploaded by making a POST request to the following endpoint http://{ip}:{port}/model
Similarly, load profile, compressed in zip format can be uploaded by making a POST request to the following endpoint http://{ip}:{port}/profiles

These files are automatically unzipped server side after a sucessful upload.

Launch the simulation¶

Make a POST request to the following endpoint http://{ip}:{port}/run (no payload needed for the POST request)

This starts the simulation. The Broker communicated with other container via REST API and singals them to start Helics co-simulation.

Retrieve simulation results¶

Identify the ips and ports information for oedisi_broker containers from the docker-compose.yml file.
Data can be downloaded by making a POST request to the following endpoint http://{ip}:{port}/download. This endpoint will communicate with all participating recorder federates ans retrieve the simulation results in a single zip file,

This will later be simplified so users are able to download all results using a single endpoint fromthe broker container.

Debugging¶

If there are timing problems, it may be helpful to pause the simulation and inspect the time. This can be done with:

oedisi build
oedisi run-with-pause

Output:

...
Enter next time: [0.0]: 1.0
Setting time barrier to 1.0

    Name         : comp_abc
    Granted Time : 0.0
    Send Time    : 0.0


    Name         : comp_xyz
    Granted Time : 0.0
    Send Time    : 0.0

We can debug components with ordinary debuggers and running that component in the foreground:

oedisi build
oedisi debug-component --foreground your_component

Testing component initialization¶

We can test the description of a component and it’s initialization without a full simulation:

oedisi test-description --component-desc component/component_definition.json --parameters inputs.json

Output:

...
Initialized broker
Waiting for initialization
Testing dynamic input names
✓
Testing dynamic output names
✓

oedisi¶

Usage

oedisi [OPTIONS] COMMAND [ARGS]...

build¶

Build to the simulation folder

Examples:

oedisi build

oedisi build --component-dict components.json --system scenario.json

Parameters¶

target_directorystr (default=”build”): build path
systemstr (default=”system.json”): path to wiring diagram json
component_dictstr (default=”components.json”): path to JSON dictionary of component folders
multi_container: bool: A boolean specifying whether or not we’re using the multi-container approach
broker_port: float: The port of the broker. If using kubernetes, is internal to k8s

Usage

oedisi build [OPTIONS]

Options

--target-directory <target_directory>¶: Target directory to put the system in

--system <system>¶: Wiring diagram json to build

--component-dict <component_dict>¶: path to JSON Dictionary of component folders

-m, --multi-container¶

Use the flag to create docker-compose config files for a multi-container implementation.

Default:: False

-p, --broker-port <broker_port>¶

Pass the broker port.

Default:: 8766

-i, --simulation-id <simulation_id>¶: Simulation ID for kubernetres or docker compose configurations.

debug-component¶

Run system runner json with one component in the JSON

We remove one component from system_runner.json and then call helics run in the background with our new json. and then run our debugging component in standard in / standard out.

Parameters¶

runnerstr: filepath to system runner json
foregroundstr: name of component

Usage

oedisi debug-component [OPTIONS]

Options

--runner <runner>¶: Location of helics run json. Usually build/system_runner.json

--foreground <foreground>¶: Name of component to run in background

evaluate-estimate¶

Evaluate the estimate of the algorithm against the measurements.

The measurements are assumed to be in the form of .feather files.

True voltages:
- voltage_real.feather
- voltage_imag.feather

Estimated voltages
- voltage_mag.feather
- voltage_angle.feather

Metrics:
- MARE: Mean absolute relative error.
- RMSRE: Root mean squared relative error.
- MAAE: Mean absolute angle error.

Parameters¶

pathPath: Path to the folder containing the measurement files.
metricstr: Metric to be used for evaluation. The options are:

Usage

oedisi evaluate-estimate [OPTIONS]

Options

--path <path>¶: path to the measurement .feather files

--metric <metric>¶

metric to be used for evaluation

Options:: MARE | RMSRE | MAAE

--angle-unit <angle_unit>¶

Unit of estimated voltages

Options:: radians | degrees

run¶

Calls out to helics run command

Examples:

oedisi run

Usage

oedisi run [OPTIONS]

Options

--runner <runner>¶: Location of helics run json. Usually build/system_runner.json

run-mc¶

Usage

oedisi run-mc [OPTIONS]

Options

--runner <runner>¶: path to the docker-compose or kubernetes deployment file

-k, --kubernetes¶

Use the flag to launch in a kubernetes pod.

Default:: False

-d, --docker-compose¶

Use the flag to launch in a kubernetes pod.

Default:: False

run-with-pause¶

Helics broker is run in the foreground, and we allow user input to block time.

Examples:

oedisi run-with-pause


Enter next time: [0.0]: 1.0
Setting time barrier to 1.0

    Name         : comp_abc
    Granted Time : 0.0
    Send Time    : 0.0


    Name         : comp_xyz
    Granted Time : 0.0
    Send Time    : 0.0

Usage

oedisi run-with-pause [OPTIONS]

Options

--runner <runner>¶: Location of helics run json. Usually build/system_runner.json

test-description¶

Test component intialization from component description

Examples:

oedisi test-description --component-desc component/component_definition.json --parameters inputs.json

Initialized broker
Waiting for initialization
Testing dynamic input names
✓
Testing dynamic output names
✓

Parameters¶

target_directorystr: build location
component_descstr: filepath to component_description.json to test
parametersstr: filepath to parameters json (default is parameters={})

Process¶

Get inputs and outputs from component_desc Create a wiring diagram for component

and a “do-nothing” component with parameters for the corresponding inputs and outputs (basically recorder federate?)

Create and run system with wiring diagram

Usage

oedisi test-description [OPTIONS]

Options

--target-directory <target_directory>¶: Target directory to put the system in

--component-desc <component_desc>¶: Path to component description

--parameters <parameters>¶: Path to parameters JSON (default is parameters={})

oedisi CLI¶

Example Usage¶

Multi-Container REST API endpoint requirements¶

Multi-Container Model Setup¶

Multi-Container Model Run¶

Upload private data¶

Launch the simulation¶

Retrieve simulation results¶

Debugging¶

Testing component initialization¶

oedisi¶

build¶

Parameters¶

debug-component¶

Parameters¶

evaluate-estimate¶

Parameters¶

run¶

run-mc¶

run-with-pause¶

test-description¶

Parameters¶

Process¶

`oedisi` CLI¶