EngineBase Schema¶

The EngineConfigs array in the simulation configuration file describes the setup of the engines that will participate in the experiment. As different types of engines require different configuration parameters, each type have a dedicated schema. For a list of the available engines and their configuration parameters see Engine implementations shipped with NRP-core.

Regardless of the chosen engine type, there is a set of parameters common to every engine. These are defined in the EngineBase schema presented in this page. From the list of EngineBase parameters, several deserve specific explanations, which are given in a section below.

Parameters¶

Name	Description	Type	Default	Required	Array
EngineName	Name of the engine	string		X
EngineType	Engine type. Used by	string		X
EngineProcCmd	Engine Process Launch command	string
EngineProcStartParams	Engine Process Start Parameters	string	[]		X
EngineEnvParams	Engine Process Environment Parameters	string	[]		X
EngineLaunchCommand		object	{“LaunchType”:”BasicFork”}
EngineTimestep	Engine Timestep in seconds	number	0.01
EngineCommandTimeout	Engine Timeout (in seconds). It tells how long to wait for the completion of the engine runStep. 0 or negative values are interpreted as no timeout	number	0.0
EngineExtraConfigs	Engine Extra Configurations which can customize certain engine functionalities. Valid configurations depend on the engine	object	{}

Example¶

{
    "EngineType": "python_json",
    "EngineName": "python_1",
    "PythonFileName": "engine_1.py"
}

Schema¶

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "title": "Engine Base",
  "description": "Base configuration schema which all engine configurations inherit from",
  "$id": "#EngineBase",
  "type": "object",
  "properties" : {
    "EngineName" : {
      "type" : "string",
      "description": "Name of the engine"
    },
    "EngineType" : {
      "type" : "string",
      "description": "Engine type. Used by EngineLauncherManager to select the correct engine launcher"
    },
    "EngineProcCmd" : {
      "type" : "string",
      "description": "Engine Process Launch command"
    },
    "EngineProcStartParams" : {
      "type" : "array",
      "items": {"type" : "string"},
      "description": "Engine Process Start Parameters"
    },
    "EngineEnvParams" : {
      "type" : "array",
      "items": {"type" : "string"},
      "description": "Engine Process Environment Parameters"
    },
    "EngineLaunchCommand" : {
      "$schema": "http://json-schema.org/draft-07/schema#",
      "title": "Engine Launch Command",
      "description": "LaunchCommand that will be used to launch the engine process",
      "$id": "#EngineLaunchCommand",
      "type":"object",
      "oneOf":[
        { "$ref": "json://nrp-core/launch_commands/empty_launch_cmd.json#/empty_launch_cmd" },
        { "$ref": "json://nrp-core/launch_commands/basicfork_cmd.json#/basicfork_cmd" },
        { "$ref": "json://nrp-core/launch_commands/docker_launcher_cmd.json#/docker_launcher_cmd" }
      ],
      "default":{"LaunchType":"BasicFork"}
    },
    "EngineTimestep" : {
      "type" : "number",
      "default": 0.01,
      "description": "Engine Timestep in seconds"
    },
    "EngineCommandTimeout" : {
      "type" : "number",
      "default": 0.0,
      "description": "Engine Timeout (in seconds). It tells how long to wait for the completion of the engine runStep. 0 or negative values are interpreted as no timeout"
    },
    "EngineExtraConfigs" : {
      "type" : "object",
      "description": "Engine Extra Configurations which can customize certain engine functionalities. Valid configurations depend on the engine"
    }
  },
  "required" : ["EngineName", "EngineType"]
}

Additional notes on parameters¶

EngineProcCmd¶

This parameter sets the command that will be used to launch the engine. As mentioned in the General notes about the use of JSON schema section, default values are allowed to be set either in the schema or in-code, by using the json_utils::setDefault function. In the later case, the parameter should be set as not required and should not have a default parameter. This is the case of EngineProcCmd.

In order to allow for flexibility in the setting of EngineProcCmd, its default value is set in-code for every engine type. This means that every new engine implementation should set a default value for EngineProcCmd in-code. For example, in the case of the NEST JSON Engine, EngineProcCmd is set to NRP_NEST_EXECUTABLE_PATH, which is an environment variable pointing to nest-simulator executable.

In any case, if a value for EngineProcCmd is set in the configuration file, it will be used for launching the engine instead of the default value.

EngineProcStartParams¶

This parameter contains an array of strings that will be added as arguments to the Engine process launch command. In order to add flexibility in the formatting on these arguments, EngineClient has a dedicated method, EngineClient::engineProcStartParams, in which the EngineProcStartParams parameter is read from the configuration file and formatted appropriately. This is a virtual method that every new engine implementation should implement.

EngineExtraConfigs¶

This parameter stores an object which contains additional configuration parameters specific to certain engines. The validation of the content is left to the engine. Its default value is set in-code to an empty object for every engine type.

Additional Configuration Parameters¶

Engine implementations may need additional in-code configuration parameters which are not present in their schemas. The convention adopted in the architecture is to store these parameters in a struct with the name EngineTypeConfigConst. For example, in the case of gazebo_json_engine exists a GazeboJSONConfigConst :

struct GazeboJSONConfigConst
{
    static constexpr char EngineType[] = "gazebo_json";
    static constexpr char EngineSchema[] = "json://nrp-core/engines/engines_gazebo.json#/engine_gazebo_json";

    static constexpr std::string_view GazeboPluginArg = "-s";

    static constexpr std::string_view GazeboRNGSeedArg = "--seed";
};

Two parameters are mandatory for every engine implementation:

EngineType : which is used to configure the engine launcher corresponding to this type of engine
EngineSchema : which contains the path to the schema that will be used to validate an engine configuration for this specific type of engine. The engine configuration is passed to the EngineClient constructor as a nlohmann::json object and validated against the specified schema in the same constructor. If the validation step fails the experiment will end with an exception.