In this second part on Simcenter Amesim’s Simulation Scripting and API we explore the Application Programming Interface (API) in more detail. The API, or Circuit API which it is also known as, provides users with similar capabilities to that of Simulation Scripting but with additional options for component selection, placement, and connection to each other. Essentially supplying users with the means to create new models in a more time-efficient and advanced way using scripting. This compared to manually adding and connecting parts in Simcenter Amesim’s GUI. For those of you who missed the previous article on Simulation Scripting, the link to that blog is supplied here: Simcenter Amesim – Simulation Scripting and API – Part 1The intention with Simcenter Amesim’s API is to provide users with a large set of Simcenter Amesim functions to write their own scripts in the languages Python, C, and Visual Basic for Applications (VBA). These lines of code may then be combined with other larger user scripted programs to automate and perform complex pre-/ post-processing tasks, execute optimization runs, or build the models used for simulation.
The API is initialized by calling the function AMEInitAPI(). This step checks out a Simcenter Amesim license and in order to release the license again once finished the function AMECloseAPI() is called. This is typically placed at the very end of a script to ensure that the license is actually released once the script is run to completion.Now, using the built in command window may be sufficient for some tasks, more often however a script containing a set of instructions is generally required to automate a task.In the short script below, the “ame_apy” module is imported and stored under its own namespace called “api” for convenience.Afterwards the API is initialized with AMEInitAPI and then AMECreateCircuit(‘MyModel’) is called to create a new and empty model titled MyModel.
Once the new model has been created, a new component can be added with the function AMEAddComponent(). This function takes in the following arguments: component icon name, alias path of the component, the components position coordinates.Finally, the model is closed and saved using the AMECloseCircuit(True). Using the True argument will save the model as well as closing it. The AMECloseAPI() is called to release the license used by the API.The simple example above provides the basis for using the API to construct a new model from scratch. The API also allows for changing parameter values, configuring a simulation run and executing that run using similar functions found when using Simulation Scripting, topics which were discussed during the previous blog article.When it comes to syntaxes and component names most of us have yet to learn all component aliases by heart. Despair not. We can speed up the scripting process by leveraging a built-in routine to convert an existing Simcenter Amesim model into Python code by the click of a button.
The generated Python script provides users with the code for setting and manipulating parameters associated with the components contained within a model. The script can be used as a template when creating a new model, or the syntax and arguments for a particular change one wants to carry out can be copied and pasted into a separate script. To sum up, this reduces the need for time-consuming and tedious trial and error work significantly.On a similar note, the API may also be used to save time when dealing with repetitive tasks containing multiple copy & paste actions. The approach of copying and pasting components several times also has the disadvantage of that each copy needs to be connected manually each time. This might not be all that severe, especially if the number of copies are low. However, it becomes impractical when considering cases where each copied component, or copied set of components, should have different internal parameter values as well. Perhaps according to some sequence, such as a change in pipe diameter based on the distance away from a pressure source, or when modelling each battery cell within a battery pack and having their thermal properties depend on their placement within the pack.In the following example, the level discretization for a Proton Exchange Membrane Fuel Cell (PEMFC) stack model was increased to study the spatial evolution of species concentrations along channels and electrodes within the PEMFC. As a result of the increased discretization, the approach also allows for assessing each individual stack segment’s contribution to the overall polarization curve.
For the model above, the level of discretization used was set to use 10 segments but this could have easily been increased if an API script was employed when creating the model.This concludes the second part of the Simulation Scripting and API blog series. Hopefully you found the read interesting and if you have questions relating to scripting or API functions in Simcenter Amesim you are welcome to reach out to us at support@volupe.com.
In this article we primarily focus on model creation and manipulation, however some of the overall capabilities available using the API are outlined below:
- Set parameters and collect results
- Run simulation tasks
- Post processing results
- Add, move, rotate and connect components on the sketch
- Assign sub-models to the components
- Compile models
- Set run parameters and automate runs
To use Simcenter Amesim’s API some general requirements need to be fulfilled:
- Correct system setup. Refer to the official Simulation Scripting and Simcenter Amesim API manuals for the specific setups for each scripting language. This may involve ensuring that the coding language and Amesim version are compatible, that the correct modules are avaiable and so on.
- For Simulation Scripting, a Simcenter Amesim Runtime license is required. For Simcenter’s Amesim API both Simcenter Amesim GUI and Libraries licenses are needed. This is since the same capabilities found in your standard installation now are available when scripting and running a model.
The API is initialized by calling the function AMEInitAPI(). This step checks out a Simcenter Amesim license and in order to release the license again once finished the function AMECloseAPI() is called. This is typically placed at the very end of a script to ensure that the license is actually released once the script is run to completion.Now, using the built in command window may be sufficient for some tasks, more often however a script containing a set of instructions is generally required to automate a task.In the short script below, the “ame_apy” module is imported and stored under its own namespace called “api” for convenience.Afterwards the API is initialized with AMEInitAPI and then AMECreateCircuit(‘MyModel’) is called to create a new and empty model titled MyModel.
Once the new model has been created, a new component can be added with the function AMEAddComponent(). This function takes in the following arguments: component icon name, alias path of the component, the components position coordinates.Finally, the model is closed and saved using the AMECloseCircuit(True). Using the True argument will save the model as well as closing it. The AMECloseAPI() is called to release the license used by the API.The simple example above provides the basis for using the API to construct a new model from scratch. The API also allows for changing parameter values, configuring a simulation run and executing that run using similar functions found when using Simulation Scripting, topics which were discussed during the previous blog article.When it comes to syntaxes and component names most of us have yet to learn all component aliases by heart. Despair not. We can speed up the scripting process by leveraging a built-in routine to convert an existing Simcenter Amesim model into Python code by the click of a button.
As seen above, the Generate model script routine may also be used to convert a model into C++ and VBA code as well.
Running this routine on our recently created model named MyModel yields the following results.
The generated Python script provides users with the code for setting and manipulating parameters associated with the components contained within a model. The script can be used as a template when creating a new model, or the syntax and arguments for a particular change one wants to carry out can be copied and pasted into a separate script. To sum up, this reduces the need for time-consuming and tedious trial and error work significantly.On a similar note, the API may also be used to save time when dealing with repetitive tasks containing multiple copy & paste actions. The approach of copying and pasting components several times also has the disadvantage of that each copy needs to be connected manually each time. This might not be all that severe, especially if the number of copies are low. However, it becomes impractical when considering cases where each copied component, or copied set of components, should have different internal parameter values as well. Perhaps according to some sequence, such as a change in pipe diameter based on the distance away from a pressure source, or when modelling each battery cell within a battery pack and having their thermal properties depend on their placement within the pack.In the following example, the level discretization for a Proton Exchange Membrane Fuel Cell (PEMFC) stack model was increased to study the spatial evolution of species concentrations along channels and electrodes within the PEMFC. As a result of the increased discretization, the approach also allows for assessing each individual stack segment’s contribution to the overall polarization curve.
For the model above, the level of discretization used was set to use 10 segments but this could have easily been increased if an API script was employed when creating the model.This concludes the second part of the Simulation Scripting and API blog series. Hopefully you found the read interesting and if you have questions relating to scripting or API functions in Simcenter Amesim you are welcome to reach out to us at support@volupe.com.Author
Fabian Hasselby, M.Sc.