This section will give a brief overview to the high-level functions, which algorithms are available at the moment, how to change settings and how the return argument is composed. The section ends with a short simulation example, but the general principle of the example also applies for the initialize and optimize functions.
The initialize, simulate and optimize functions are all located in the package jmodelica. There are two main ways of making them available in the Python shell or in a script
Import the package jmodelica. This will create a new namespace with all attributes from the
jmodelicapackage. To use any of the functions, the package name must then be used as a prefix.# import the optimize function by importing jmodelica import jmodelica # optimize is now available jmodelica.optimize <function optimize at 0x05FE8970> # so is simulate and initialize jmodelica.simulate <function simulate at 0x05FF4FB0> jmodelica.initialize <function initialize at 0x05FF6030>
Import a specific function. Using the
fromstatement a specific function will be imported in the current namespace.# import the simulate function from jmodelica from jmodelica import simulate # type simulate and hit enter simulate <function simulate at 0x05FF8170>
Note that neither
optimizenorinitializeis available now, they must also be imported explicitly.# type optimize and hit enter NameError: name 'optimize' is not defined # import optimize from jmodelica import optimize optimize <function optimize at 0x05FEDAF0>
The only required input to any of the high-level functions is the model object, the rest of the arguments all have default values. The default values are listed in the docstring of the function. Using the interactive help in the Python shell or looking at the API documentation will display the docstring for a certain function. It is then possible to see what arguments are available and their default values.
# docstring for simulate
Docstring:
Compact function for model simulation.
The intention with this function is to wrap model compilation, creation of
a model object and simulation in one function call. The simulation
method depends on which algorithm is used, this can be set with the
function argument 'algorithm'. Arguments for the algorithm and solver are
passed as dicts. Which arguments that are valid depends on which algorithm
is used, see the algorithm implementation in algorithm_drivers.py for details.
The default algorithm for this function is AssimuloAlg.
The simplest way of using the function is to pass the model name and path
to the model file (a jmi.Model is enough if model is already compiled) and
use the default values for all other arguments.
Parameters::
model --
Model object or model name (supply model name if model should be
(re)compiled, then mo-file must also be provided)
file_name --
Path to model file or list of paths to model files.
Default: empty string (no compilation)
compiler --
Set compiler that model should be compiled with, 'modelica' or
'optimica'.
Default: 'modelica'
compiler_target --
Target argument to compiler.
Default: 'ipopt'
compiler_options --
Dict with options for the compiler (see options.xml for possible
values).
Default: empty dict
algorithm --
The algorithm which will be used for the simulation is
specified by passing the algorithm class in this argument. The
algorithm class can be any class which implements the abstract
class AlgorithmBase (found in algorithm_drivers.py). In this way
it is possible to write own algorithms and use them with this
function.
Default: AssimuloAlg
alg_args --
All arguments for the chosen algorithm should be listed in this dict.
Valid arguments depend on the algorithm chosen, see algorithm
implementation in algorithm_drivers.py for details.
Default: empty dict
solver_args --
All arguments for the chosen solver should be listed in this dict.
Valid arguments depend on the chosen algorithm and possibly which
solver has been selected for the algorithm. See algorithm
implementation in algorithm_drivers.py for details.
Default: empty dict
Returns::
Result object, subclass of algorithm_drivers.ResultBase.The alg_args and solver_args are arguments for the algorithm and solver chosen, they will be passed on to the algorithm in the high-level function call. The next section will list the alg_args options for all algorithms and their default values. The solver_args argument will be explained in the section after that.
The content of the alg_args argument is different depending on which algorithm is used. The argument is a dict with default values for all options. The following tables will list the options available in the alg_args argument for each algorithm.
Table 5.1. alg_args options for AssimuloAlg
| Option | Description | Default value |
|---|---|---|
start_time | Simulation start time. | 0.0 |
final_time | Simulation stop time. | 1.0 |
num_communication_points | Number of points where the solution is returned. If set to 0 the integrator will return at it's internal steps. | 500 |
solver | Set which solver to use with class name as string. This determines whether a DAE or ODE problem will be created. | 'IDA' |
input_trajectory | Trajectory data for model inputs. The argument should be a matrix where the first column represents time and the following columns represents input trajectory data. | An empty matrix, i.e., no input trajectories. |
initialize | Do initialization if True, skip initialization if False. | True |
Table 5.2. alg_args options for AssimuloFMIAlg
| Option | Description | Default value |
|---|---|---|
start_time | Simulation start time. | 0.0 |
final_time | Simulation stop time. | 1.0 |
num_communication_points | Number of points where the solution is returned. If set to 0 the integrator will return at it's internal steps. | 500 |
solver | Set which solver to use with class name as string. | 'CVode' |
input_trajectory | Trajectory data for model inputs. The argument should be a matrix where the first column represents time and the following columns represents input trajectory data. If the input_trajectory is set the property input_names in solver_args must be set and reflect the variables for which the input is going to be adjusted. | An empty matrix, i.e., no input trajectories. |
Table 5.3. alg_args options for CollocationLagrangePolynomialsAlg
| Option | Description | Default value |
|---|---|---|
n_e | Number of finite elements. | 50 |
n_cp | Number of collocation points. | 3 |
hs | Vector containing the normalized element lengths. | Equidistant points using default n_e. |
blocking_factors | Blocking factor vector. | None (not used) |
init_traj | A reference to an object of type ResultDymolaTextual or ResultDymolaBinary containing variable trajectories used to initialize the optimization problem. | None (i.e. not used, set this argument to activate initialization) |
result_mesh | Determines which function will be used to get the solution trajectories. Possible values are, 'element_interpolation', 'mesh_interpolation' or 'default'. See optimization.ipopt for more info. | 'default' |
result_file_name | Name of result file. | Empty string (default generated file name will be used) |
result_format | Format of result file. | 'txt' |
n_interpolation_points | The number of points in each finite element at which the result is returned. Only available for result_mesh = 'element_interpolation'. | None |
The solver_args argument is a dict of options for the solver selected for the algorithm. The options depend on which solver has been chosen and the best way to find what options are available is to check the documentation for the specific solver. One limitation is that the options in the solver must be implemented as Python properties.
The solvers and corresponding options available in the Assimulo package can be found on the Assimulo web page.
Every algorithm returns its own result object and all result objects have a common base class jmodelica.algorithm_drivers.ResultBase. This means that no matter which algorithm is used in the high-level function, the function will always return an object which can be manipulated with the methods and properties of the ResultBase class.
Table 5.4. The jmodelica.algorithm_drivers.ResultBase class
| Method | Property | Description |
|---|---|---|
get_model() | model | The jmodelica.jmi.Model object that was used in the algorithm. |
get_result_file_name() | result_file_name | The name of the result file created on the file system. |
get_solver() | solver | The solver used in the algorithm. |
get_result_data() | result_data | The result data object containing the whole initialization, simulation or optimization result matrix. |
The algorithms that are used in the high-level functions are implemented as classes in the module jmodelica.algorithm_drivers. They are all subclasses of the base algorithm class jmodelica.algorithm_drivers.AlgorithmBase which contains methods that all algorithm classes must implement. The currently available algorithms are displayed in the table below.
Table 5.5. Algorithms accessible from high-level functions
| Algorithm | Use in | Default | Returns |
|---|---|---|---|
AssimuloAlg | simulate | yes | AssimuloSimResult |
AssimuloFMIAlg | simulate | no | AssimuloSimResult |
CollocationLagrangePolynomialsAlg | optimize | yes | CollocationLagrangePolynomialsResult |
IpoptInitializationAlg | initialize | yes | IpoptInitResult |
JFSInitAlg | initialize | no | JFSInitResult |
Here is a short example which will demonstrate how to use the high-level function simulate. The RLC circuit model will be used in the example. This model and a Python script which runs the example can be found in the jmodelica.examples package.
Start by creating the model object:
# The model name and mo-file model_name = 'RLC_Circuit' mo_file = 'RLC_Circuit.mo' # Create jmi.Model object from jmodelica import jmi rlc_model = jmi.Model(model_name, mo_file)
Then import the simulate function and simulate using all default arguments, this means that the AssimuloAlg algorithm will be used. Save the result object in a variable.
# Import simulate from jmodelica import simulate # Simulate with default arguments and save the result object in a variable sim_res = simulate(model_name, mofile)
The result data can then be extracted from the result object and plotted.
# Get the result data and plot some signals
res = sim_res.result_data
sine_y = res.get_variable_data('sine.y')
resistor_v = res.get_variable_data('resistor.v')
inductor1_i = res.get_variable_data('inductor1.i')
The default simulation time for the AssimuloAlg algorithm is 1s. This can be changed by altering the algorithm argument 'final_time'
# Simulate again, this time with 'final_time' set to 30s
sim_res = simulate(model_name, mofile), alg_args={'final_time':30})
Plotting with the same commands gives the result which can be seen in the figure below.
