Energetic Macroscopic Representation (EMR) is a graphical tool used to organize simulation models. EMR formalism is based on action reaction principle, which organizes the system model as interconnected subsystems according to the integral causality. An inversion of this description leads to macro-control blocks.
EMR formalism has been introduced for research development in complex electromechanical drives (Bouscayrol et al., 2000) [1]. Additional information about the EMR methodology and its applications can be found at the EMR website, hosted by the University of Lille.
EMR library in Typhoon HIL Schematic Editor is comprised of components which implement EMR pictograms.
EMR pictograms for simulation, estimation, control, and power adaptation are supported.
The components are implemented as empty subsystems.
Examples of using EMR formalism to model an electric vehicle can be found in the examples directory of this repository.
- Download and install Typhoon HIL Control Center,
- Download the EMR Library from this GitHub repository,
- Include the EMR library in the Schematic Editor.
The steps for downloading the Typhoon HIL Control Center can be found at the software download page. The Schematic Editor is one of the tools within the Typhoon HIL Control Center toolchain.
In order to download the project of the GitHub repository, click the Code button on the right hand side at the top of the page, then the Download ZIP button.
The described manner of downloading the project is in user only mode, where only the latest releases are downloaded and used.
The project can also be used in developer mode, in which easy access to the latest state of the software is available.
Contribution to the project is possible in the developer mode, while abiding by the contribution guidelines.
In developer mode, the project can be cloned using one of the provided options (HTTPS, SSH, GitHub CLI). In order to clone the project, git software and a GitHub account are required.
A quick guide for including the EMR library in the Schematic Editor is provided.
- In the Schematic Editor, click on File | Modify library paths....
- Click Browse and set the path to the emr-typhoon-hil-library / libs directory (where the EMR library is located).
- Click Apply and Save.
- Click File | Reload libraries in order to load the library.
Once the described steps have been carried out, the library will be automatically loaded the next time Schematic Editor is opened.
More detailed description of the steps for including libraries in the Schematic Editor, as well as some additonal options can be found in the Loading libraries guide.
Any contributions and suggestions for new features would be greatly appreciated!
Contributions to this GitHub hosted project are managed with GitHub flow, through the addition of issues and pull requests.
Bugs are reported using GitHub's issues. Prior to creating a new bug related issue, it should be checked that the bug hasn't already been reported under project's Issues. In addition, the project should be locally updated to its latest version.
Produce a clear bug report by providing the description of the expected and the defective behaviour. If possible, the bug report should also contain the steps necessary to reproduce the issue. Other additional information, if available, would be useful for debugging. That might be the schematic model where the bug is noticed, a traceback, an image of the erroneous behaviour, etc.
A new example should be located in the examples directory of this repository, under a new dedicated directory.
A new component can be added by updating the libs/emr.tlib library description file.
A component contains input and output ports specification, and the specification for the mask containing component properties. Basic component architecture description is provided in the following.
Each component is defined in a dedicated section. Format of the declaration for the component section is given the example below:
component Subsystem "Component Name" {
# component structure
}
Component names can consist of multiple words.
Format of the port definition is given in the example below:
port "P1" {
position = -40, -16
kind = sp
direction = out
}
[
position = 7256, 8000
hide_terminal_label = True
]
Each port is declared with its name, followed by its description. First, the main port description is specified, in which it's described how the port is seen on the component's mask. This part is placed inside curly brackets {}. It contains several attributes:
| Attribute | Description |
|---|---|
| position | Specifies the ports x and y coordinate relative to the center of the component's mask. Note: The direction of the x coordinate is from left to right, and the direction of the y coordinate is from top to bottom. |
| kind | sp, pe The sp keyword signifies that the port's type is signal processing, while pe indicates power electronic ports. |
| direction | in, out Specifies the direction of the port side which is used in the internal component structure. The complementary port side, used to connect the component with other components, is automatically deduced from this. |
Note: The described constants which indicate port's kind and direction correspond to the constants given in the Typhoon API documentation.
This description is followed by the description of the port in the internal component structure. This part is placed inside square brackets []. It contains several attributes:
| Attribute | Description |
|---|---|
| position | Specifies the ports x and y coordinate relative to the center of the top left corner of the whole scene. Schematic scene size is 16k pixels (16384), so scheme scene center point is (8192, 8192). |
| scale | Scales the two sides of the port. For example: scale = -1, 1. In this example, the port is fliped around the horizontal axis (left-right). |
| hide_terminal_label | True, False If set to True, it hides the terminal label. |
Mask definition specifies the attributes of the mask and the customized properties (widgets).
Mask definition for the Mono-Physical Converter component from the EMR Library is given below:
mask {
icon = "image('emr_images/emr_mono_physical_converter.svg')"
description = "Mono-physical converter block for Energetic Macroscopic Representation of models."
block_type {
label = "Block type"
widget = combo
combo_values = "Simulation", "Estimation"
type = string
default_value = "Simulation"
CODE property_value_changed
mdl.refresh_icon(container_handle)
ENDCODE
}
CODE define_icon
images = {"Simulation": "emr_images/emr_mono_physical_converter.svg",
"Estimation": "emr_images/emr_mono_physical_converter_estimation.svg"}
block_type = mdl.get_property_value(mdl.prop(item_handle, "block_type"))
mdl.set_component_icon_image(item_handle, images[block_type])
ENDCODE
}
The mask has the following attributes:
| Attribute | Description |
|---|---|
| icon | Defines the relative path to the component's image. |
| description | Describes the component. |
Properties have the following attributes:
| Attribute | Description | Necessity |
|---|---|---|
| label | Label on the property dialog indicating which widget represents which property. | Optional |
| widget | edit, combo, checkbox, togglebutton Defines the representation of the property on the property dialog. |
Mandatory |
| combo_values | Contains the list of values that will be shown in the combo widget. | Used only if widget is set to combo. |
| type | int, uint, real, string, bool, generic Note: When setting widget to combo, the type attribute must be set to string. |
Mandatory |
| default_value | Sets the property's value when the component is added to the schematic model. | Mandatory |
An image is linked to the component in the mask definition of the component, by setting the icon property. The icon property contains the path to the component's image relative to the location of the library description .tlib file.
Images should be saved in .svg format. A new component image should be located in the libs/emr_images directory of this project.
Any contributions you make will be under the MIT Software License.
In short, when you submit code changes, your submissions are understood to be under the same MIT License that covers the project. Feel free to contact the maintainers if that's a concern.
[1] A. Bouscayrol, B. Davat, B. de Fornel, B. François, J. P. Hautier, F. Meibody-Tabar, M. Pietrzak-David, Multi-converter multi-machine systems: application for electromechanical drives, EPJ Applied Physics, vol. 10, no. 2, May 2000, pp. 131-147.
[2] A. Genic, C. Mayet, M. Almeida, A. Bouscayrol, N. Stojkov. EMR-Based Signal-HIL Testing of an Electric Vehicle Control, 2017 IEEE Vehicle Power and Propulsion Conference (VPPC), 2017, pp. 1-6