Terminology

CoSim Toolbox (CST) has defined a data model that provides a consistent terminology throughout the APIs (regardless of the underlying tool) and provides a means of thinking more concretely about the work being planned. The following are the terms of art used in CST:

“analysis”

This is the highest level of abstraction when thinking about the work being conducted in the co-simulation. The analysis describes the goals of the work and what comparisons are being made in the study. The analysis will define the parameters being varied to enable the comparisons where a given set of parameter values will define a scenario (see below). The concept of “analysis” manifests most visibly in the metadata and time-series APIs where groupings of simulation results (again, defined by a scenario) are collected.

“scenario”

A “scenario” is a specific set of analysis parameters that are defined to create a single case for study. The goals of the analysis are revealed through the comparison between one or more scenarios. For example, the analysis may call out that a comparison needs to be made between a particular model with and without electric vehicles; this requires the definition of two scenarios. The definition of the scenarios is stored in the metadata database and is used by the CST APIs to configure federates (defined below). This information is also useful when evaluating co-simulation output data to see the values of the analysis parameters when creating graphs, tables, and charts in post-processing. Scenario data can also be extended to include information beyond analysis parameters directly used in the configuration of the co-simulation. Data in the time-series database uses the “scenario” value as a key parameter when storing the data.

“federate”

A “federate” is an instance of a simulation tool with a specific model and/or data set. For example, there may be a tool that simulates a single neighborhood in the power system. Every time this simulator is instantiated in the co-simulation and a different neighborhood is modeled, a new federate is defined with a unique name. In HELICS (the underlying co-simulation platform used by CST), each federate needs specific configuration information to join the co-simulation as defined by the analysis. Data in the time-series database uses the “federate” value as a key parameter when storing the data. CST provides a federate class that makes creating a new federate simpler by providing more-convenient wrappers and access methods for the HELICS APIs. The federate class

“federation”

Each scenario defines a set of federates to be used to model all the is required for that scenario and this collection of the federates is called the “federation”. All federates in the federation are defined in the metadata database. Generally, there is a strong overlap in the federation definition between scenarios in a given analysis. CST provides APIs that makes defining a federation and its corresponding data exchanges easier.

Note on Terminology

The definitions presented here are primarily used when constructing the databases and the CST APIs developed to access them. Using any unique combination “analysis” and “scenario” will guarantee data and metadata is not overwritten from previous co-simulation runs. Additionally, it is possible that the configuration metadata stored in the database is intended to be used across multiple scenarios and analysis.