.. index:: pair: page; EngineBase Schema .. _doxid-engine_base_schema: 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 :ref:`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 :ref:`below `. .. _doxid-engine_base_schema_1engine_base_schema_parameters: 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 {} ===================== =================================================================================================================================================== ====== ========================== ======== ===== .. _doxid-engine_base_schema_1engine_base_schema_example: Example ~~~~~~~ .. ref-code-block:: cpp { "EngineType": "python_json", "EngineName": "python_1", "PythonFileName": "engine_1.py" } .. _doxid-engine_base_schema_1engine_base_schema_schema: Schema ~~~~~~ .. ref-code-block:: cpp { "$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"] } .. _doxid-engine_base_schema_1specific_parameters: Additional notes on parameters ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. _doxid-engine_base_schema_1engine_proc_command: EngineProcCmd ------------- This parameter sets the command that will be used to launch the engine. As mentioned in the :ref:`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 :ref:`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. .. _doxid-engine_base_schema_1engine_proc_start_params: 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, :ref:`EngineClient ` has a dedicated method, :ref:`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**. .. _doxid-engine_base_schema_1engine_extra_configs: 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. .. _doxid-engine_base_schema_1additional_engine_configuration: 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 :ref:`GazeboJSONConfigConst ` : .. ref-code-block:: cpp struct :ref:`GazeboJSONConfigConst ` { static constexpr char :ref:`EngineType `[] = "gazebo_json"; static constexpr char :ref:`EngineSchema `[] = "json://nrp-core/engines/engines_gazebo.json#/engine_gazebo_json"; static constexpr std::string_view :ref:`GazeboPluginArg ` = "-s"; static constexpr std::string_view :ref:`GazeboRNGSeedArg ` = "--seed"; }; Two parameters are mandatory for every engine implementation: * ``EngineType`` : which is used to configure the :ref:`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 :ref:`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.