=============== Characteristics =============== .. toctree:: :hidden: :glob: Characteristics in EOS are used to map some nummeric input to nummeric output based on statitical data. Typical use case is when you dont wont or cannot use mathematical formula to compute output for some input data in case of too complex or even unknown physics behind it. In general there is two types of chacteristics in EOS. - `Characteristic 2D` maps single nummeric input (X-Axis) value to single output (Y-Axis) value. For example to get needed corresponding electric current value (output) for some voltage value (input). - `Characteristic 3D` maps pair values of nummeric input (X- and Y-Axis) to single (Z-Axis) or pair (Z- and W-Axis) nummeric output values. 1. Characteristic 2D ==================== Characteristics 2D needs to be defined at Structure Class and describe his input and output physical units. Create/Update characteristic 2d ------------------------------- To create or change Characteristic 2D execute transactional POST request at URL: .. code:: console characteristic/2d/save_or_update/trx=[TRX_ID] with JSON Object: .. code:: typescript { "id": 1, // Id of characteristic object. Use `null` if new. "key": null, // Text identifier used in custom calculation algorithms (optional) "structure_class": { "id": 52 // Id of structure class to be referenced }, "location": null, // Location within class (optional) "medium": { // Medium of described property "value": "EE", "name": "Elektroenergie" }, "input_physical_unit": "electric current", // Input value physical unit key "input_measuring_unit": "electric current / ampere", // Input value measuring unit key "output_physical_unit": "voltage", // Output value physical unit key "output_measuring_unit": "voltage / volt", // Output value measuring unit key "specialization": { // Spezialization of described property (optional) "id": 152, "value": "kl1", "name": "Kennlinie 1" }, "description": "Hesop Kennlinie 1 a", // Optional description "input_values_bounds": null, // Optional reference to input values bounds "output_values_bounds": null, // Optional reference to output values bounds "role_ids": [], // Opotional array of assigned roles. "instances": [ // ids of instances of this characteristic 2d for all objects of structure class. 1 // Automaticaly filled at creation/update of undelying model. ], "structure_class_token": "HESOP" // Only for client visualisazion. Ignored on server side. } Characteristic 2D instances and characteristic functions -------------------------------------------------------- Characteristic 2D instance is a representation of characteristic 2D for some `Structure Object` of a `Structure Class` and can contain multiple characteristic functions. Characteristic 2D functions contains equal sized arrays of X/Y-Axis points in 2-dimensional space. Output values are calculated over interpolation between two such point left and right of input value. Every characteristic 2D function have its begin of validity and is active until begin of next function validity. To get all characteristic 2D instance for given `Structure Object` use GET request: .. code:: console characteristic/2d_instance/get/trx=[TRX_ID]&c2d_id=[C2D_ID]&object_id=[STRUCTURE_OBJECT_ID] You cann also get characteristic 2D instance over its id: .. code:: console characteristic/2d_instance/get/trx=[TRX_ID]&id=[C2D_INSTANCE_ID] Response JSON example: .. code:: typescript { "id": 54, "characteristic": { "id": 54 }, "structure_object": { "id": 7052 }, "input_values_bounds": null, "output_values_bounds": null, "functions": [ // List of characteristic 2D functions { "from": "2021-06-11T15:52:30Z", // begin of function validity "function": { "input_m_u": "electric current / ampere", // measuremenet unit of input edge points "output_m_u": "voltage / volt", // measurement unit of output edge points "input_low_limit": null, "input_high_limit": null, "output_low_limit": null, "output_high_limit": null, "input_values": "wI6UdcUdcUfAiITNmTNmTcCGuMOeMOeMwIS98Qd8Qd/AgZrSlrSlrsB3skbckbckwGwyC4yC4yDAXEPeEPeEQEBfrSlrSlrQQG34g74g74hAc+tqStqStEB5tOWNOWNMQH9+YM+YM+hAhbd0Rd0ReECN4R9wR9wS", // Base64 encoded array of double input values "output_values": "QIL5MN/rVJ5Ag6ggugZ1j0CEvawHwETmQIXMfODHzgxAhojhpEd7X0CHAf3Y0GrLQIZlz3THq7xAhxmKcUBgdUCHNHRECXk4QIdKUj9M3VZAh68/Fb76MECIkKVbEymOQIlhOXypqXJAiYLdxCUIZkCJpIILoGdZ" // Base64 encoded array of double output values } }, { "from": "2021-06-11T17:00:00Z", // begin of function validity "function": { "input_m_u": "electric current / ampere", // measuremenet unit of input edge points "output_m_u": "voltage / volt", // measurement unit of output edge points "input_low_limit": null, "input_high_limit": null, "output_low_limit": null, "output_high_limit": null, "input_values": "wImcZBcZBcbAfBP4TP4TQEA+Ez+Ez+FAQIJTurTurTxAjF8oa8oa8g\u003d\u003d", // Base64 encoded array of double input values "output_values": "QIQiNDUfmWtAhS6KTdpyfkCJg6nnRSbtQIiervDjJgNAijL6C+gvoQ\u003d\u003d" // Base64 encoded array of double output values } } ] } In this example we have two characteristic functions assigned to characteristic 2d instance. The first one is valid from 2021-06-11T15:52:30 UTC and second from 2021-06-11T17:00:00 UTC time. To add/update/delete characteristic functions send list of function changes to variable instance over POST request: .. code:: console characteristic/2d_instance/apply_curve_changes/trx=[TRX_ID]&id=[C2D_INSTANCE_ID] To add new function: .. code:: typescript [ { "old_begin": null, // new function have no prev begin validity timestamp "new_begin": "2021-06-11T17:00:00Z", // begin timestamp "function": { "input_m_u": "electric current / ampere", "output_m_u": "voltage / volt", "input_low_limit": null, "input_high_limit": null, "output_low_limit": null, "output_high_limit": null, "input_values": "wImcZBcZBcbAfBP4TP4TQEA+Ez+Ez+FAQIJTurTurTxAjF8oa8oa8g\u003d\u003d", "output_values": "QIQiNDUfmWtAhS6KTdpyfkCJg6nnRSbtQIiervDjJgNAijL6C+gvoQ\u003d\u003d" } } ] To change edge points or begin of timestamp: .. code:: typescript [ { "old_begin": "2021-06-11T17:00:00Z", // Old timestamp of function "new_begin": "2021-06-12T18:31:00Z", // New begin timestamp "function": { "input_m_u": "electric current / ampere", "output_m_u": "voltage / volt", "input_low_limit": null, "input_high_limit": null, "output_low_limit": null, "output_high_limit": null, "input_values": "wImcZBcZBcbAfBP4TP4TQEA+Ez+Ez+FAQIJTurTurTxAjF8oa8oa8g\u003d\u003d", "output_values": "QIQiNDUfmWtAhS6KTdpyfkCJg6nnRSbtQIiervDjJgNAijL6C+gvoQ\u003d\u003d" } } ] To delete function: .. code:: typescript [ { "old_begin": "2021-06-11T17:00:00Z", // Old timestamp of function "new_begin": null, // New begin timestamp (null) "function": null } ] You can also combine multiple changes in one request 2. Characteristic 3D ==================== ... // Missing documentation