This page contains the Algorithm_Drivers Module documentation.
Module for optimization, simulation and initialization algorithms to be used together with jmodelica.jmi.JMUModel.optimize, jmodelica.jmi.JMUModel.simulate, jmodelica.fmi.FMUModel.simulate and jmodelica.jmi.JMUModel.initialize respectively.
Bases: object
Abstract class which all algorithms that are to be used with jmodelica.jmi.JMUModel.optimize, jmodelica.jmi.JMUModel.simulate, jmodelica.fmi.FMUModel.simulate or jmodelica.jmi.JMUModel.initialize must implement.
Bases: jmodelica.algorithm_drivers.AlgorithmBase
Simulation algorithm using the Assimulo package.
Get an instance of the options class for the AssimuloAlg algorithm, prefilled with default values. (Class method.)
Bases: jmodelica.algorithm_drivers.OptionBase
Options for simulation of a JMU model using the Assimulo simulation package. The Assimulo package contain both explicit solvers (CVode) for ODEs and implicit solvers (IDA) for DAEs. The ODE solvers require that the problem is written on the form, ydot = f(t,y).
Assimulo options:
solver --
Specifies the simulation algorithm that is to be used.
Default 'IDA'
ncp --
Number of communication points. If ncp is zero, the solver will
return the internal steps taken.
Default '0'
initialize --
If set to True, an algorithm for initializing the differential
equation is invoked, otherwise the differential equation is assumed
to have consistent initial conditions.
Default is True.
write_scaled_result --
Set this parameter to True to write the result to file without
taking scaling into account. If the value of scaled is False, then
the variable scaling factors of the model are used to reproduced the
unscaled variable values.
Default: False
result_file_name --
Specifies the name of the file where the simulation result is
written. Setting this option to an empty string results in a default
file name that is based on the name of the model class.
Default: Empty string
The different solvers provided by the Assimulo simulation package provides different options. These options are given in dictionaries with names consisting of the solver name concatenated by the string ‘_option’. The most common solver options are documented below, for a complete list of options see, http://www.jmodelica.org/assimulo
Options for IDA:
rtol --
The relative tolerance.
Default: 1.0e-6
atol --
The absolute tolerance.
Default: 1.0e-6
maxord --
The maximum order of the solver. Can range between 1 to 5. Note,
when simulating sensitivities the maximum order is limited to 4.
This is a temporary restriction.
Default: 5
sensitivity --
If set to True, sensitivities for the states with respect to
parameters set to free in the model will be calculated.
Default: False
write_cont --
Continuous writing of the result file instead. Currently only
supported when "sensitivity" is set to True.
Default: False
Options for CVode:
rtol --
The relative tolerance.
Default: 1.0e-6
atol --
The absolute tolerance.
Default: 1.0e-6
discr --
The discretization method. Can be either 'BDF' or 'Adams'.
Default: 'BDF'
iter --
The iteration method. Can be either 'Newton' or 'FixedPoint'.
Default: 'Newton'
Bases: jmodelica.algorithm_drivers.AlgorithmBase
Simulation algortihm for FMUs using the Assimulo package.
Get an instance of the options class for the AssimuloFMIAlg algorithm, prefilled with default values. (Class method.)
Bases: jmodelica.algorithm_drivers.OptionBase
Options for the solving the FMU using the Assimulo simulation package. Currently, the only solver in the Assimulo package that fully supports simulation of FMUs is the solver CVode.
Assimulo options:
solver --
Specifies the simulation algorithm that is to be used. Currently the
only supported solver is 'CVode'.
Default: 'CVode'
ncp --
Number of communication points. If ncp is zero, the solver will
return the internal steps taken.
Default: '0'
initialize --
If set to True, the initializing algorithm defined in the FMU model
is invoked, otherwise it is assumed the user have manually invoked
model.initialize()
Default is True.
write_scaled_result --
Set this parameter to True to write the result to file without
taking scaling into account. If the value of scaled is False,
then the variable scaling factors of the model are used to
reproduced the unscaled variable values.
Default: False
result_file_name --
Specifies the name of the file where the simulation result is
written. Setting this option to an empty string results in a default
file name that is based on the name of the model class.
Default: Empty string
with_jacobian --
Set to True if an FMU Jacobian for the ODE is available or
False otherwise.
Default: False
The different solvers provided by the Assimulo simulation package provides different options. These options are given in dictionaries with names consisting of the solver name concatenated by the string ‘_option’. The most common solver options are documented below, for a complete list of options see, http://www.jmodelica.org/assimulo
Options for CVode:
rtol --
The relative tolerance. The relative tolerance are retrieved from
the 'default experiment' section in the XML-file and if not
found are set to 1.0e-4
Default: "Default" (1.0e-4)
atol --
The absolute tolerance.
Default: "Default" (rtol*0.01*(nominal values of the continuous states))
discr --
The discretization method. Can be either 'BDF' or 'Adams'
Default: 'BDF'
iter --
The iteration method. Can be either 'Newton' or 'FixedPoint'
Default: 'Newton'
Bases: jmodelica.algorithm_drivers.AlgorithmBase
The algorithm is based on orthogonal collocation and relies on the solver IPOPT for solving a non-linear programming problem.
Get an instance of the options class for the CollocationLagrangePolynomialsAlg algorithm, prefilled with default values. (Class method.)
Bases: jmodelica.algorithm_drivers.OptionBase
Options for optimizing JMU models using a collocation algorithm.
Collocation algorithm options:
n_e --
Number of phases of the finite element mesh.
Default: 1
n_cp --
Number of collocation points in each phase (element).
Default: 20
discr --
Determines the discretization of the problem. Could be either
LG (Legendre-Gauss), LGR (Legendre-Gauss-Radau), LGL (Legendre-
Gauss-Lobatto)
Default: "LG"
link_options --
This option allows users to specify states that are allowed to be
discontinuous between phases (elements) and to connect the
transition with a model parameter. Example, [(1,"x1","dx1")], this
allowes the variable x1 to be discontinuous between phase 1 and 2
with the parameter dx1. The generating constraint becomes,
x1_N^1 - x1_0^2 - dx1 = 0. There is no limit that the same
parameter can be used in multiple transition such as,
[(1,"x1","dx1"), (1,"x2","dx1"), (2,"x1","dx1")]
Default: []
phase_options --
This options allows users to connect parameters to phase boundaries
(time). Example, in a three phase problem the parameters t1 and t2
can be specified to be the boundaries of the phases such as,
["t1", "t2"], the option free_phases have also be set to true.
Default: None
free_phases --
Specifies if the location of the phases should be allowed to be
changed by the optimizer.
Default: False
n_interpolation_points --
Number of interpolation points in each finite element.
Default: None
init_traj --
Variable trajectory data used for initialization of the optimization
problem. The data is represented by an object of the type
jmodelica.io.DymolaResultTextual.
Default: None
result_mode --
Specifies the output format of the optimization result.
- 'default' gives the the optimization result at the collocation
points.
Default: 'default'
result_file_name --
Specifies the name of the file where the optimization result is
written. Setting this option to an empty string results in a default
file name that is based on the name of the optimization class.
Default: Empty string
result_format --
Specifies in which format to write the result. Currently
only textual mode is supported.
Default: 'txt'
write_scaled_result --
Write the scaled optimization result if set to true. This option is
only applicable when automatic variable scaling is enabled. Only for
debugging use.
Default: False.
Options are set by using the syntax for dictionaries:
>>> opts = my_model.optimize_options()
>>> opts['n_e'] = 100
In addition, IPOPT options can be provided in the option IPOPT_options. For a complete list of IPOPT options, please consult the IPOPT documentation available at http://www.coin-or.org/Ipopt/documentation/).
Some commonly used IPOPT options are provided by default:
max_iter --
Maximum number of iterations.
Default: 3000
derivative_test --
Check the correctness of the NLP derivatives. Valid values are
'none', 'first-order', 'second-order', 'only-second-order'.
Default: 'none'
IPOPT options are set using the syntax for dictionaries:
>>> opts['IPOPT_options']['max_iter'] = 200
Bases: jmodelica.algorithm_drivers.AlgorithmBase
The algorithm is based on orthogonal collocation and relies on the solver IPOPT for solving a non-linear programming problem.
Get an instance of the options class for the CasadiRadau algorithm, prefilled with default values. (Class method.)
Bases: jmodelica.algorithm_drivers.AlgorithmBase
The algorithm is based on orthogonal collocation and relies on the solver IPOPT for solving a non-linear programming problem.
Get an instance of the options class for the CasadiRadau2 algorithm, prefilled with default values. (Class method.)
Write result to file, load result data and create a CasadiRadau2Result object.
Returns:
The CasadiRadau2Result object.
Solve the optimization problem using ipopt solver.
Bases: jmodelica.algorithm_drivers.OptionBase
Options for optimizing JMU models using a collocation algorithm.
Collocation algorithm options:
n_e --
Number of finite elements.
Type: int
Default: 50
hs --
Element lengths.
Possible values: None, list of floats and "free"
None: The element lengths are uniformly distributed.
list of floats: Component i of the list specifies the length of
element i. The lengths must be normalized in the sense that the sum
of all lengths must be equal to 1.
"free": The element lengths become optimization variables and are
optimized according to the algorithm option
free_element_length_data.
WARNING: This option is very experimental and will not always give
desirable results.
Type: None, list of floats or string
Default: None
free_element_lengths_data --
Data used for optimizing the element lengths if they are free.
Should be None if and only if hs != "free".
Type: None or jmodelica.optimization.free_element_length_data
Default: None
n_cp --
Number of collocation points in each element.
Type: int
Default: 3
graph --
CasADi graph type. Possible values are "SX", "MX" and
"expanded_MX".
Type: str
Default: "SX"
write_scaled_result --
Return the scaled optimization result if set to True, otherwise
return the unscaled optimization result. This option is
only applicable when the CasadiModel has been compiled with
enable_scaling=True. This option is only intended for debugging.
Type: bool
Default: False
result_mode --
Specifies the output format of the optimization result.
Possible values: "collocation_points" and "element_interpolation"
"collocation_points": The optimization result is given at the
collocation points.
"element_interpolation": The values of the variable trajectories
are calculated by evaluating the collocation interpolation
polynomials. The algorithm option n_evaluation_points is used to
specify the evaluation points within each finite element.
Type: str
Default: "collocation_points"
n_eval_points --
The number of evaluation points used in each element when the
algorithm option result_mode is set to "element_interpolation". One
evaluation point is placed at each element end-point (hence the
option value must be at least 2) and the rest are distributed
uniformly.
Type: int
Default: 20
blocking_factors --
The list of blocking factors, where each element corresponds to the
number of elements for which the control profile should be
constant. For example, if blocking_factor == [2, 1, 5], then
u_0 = u_1 and u_3 = u_4 = u_5 = u_6 = u_7. The sum of all elements
in the list must be the same as the number of elements.
If blocking_facotrs is None, then Lagrange polynomials are instead
used to represent the control.
Type: None or list of ints
Default: None
eliminate_der_var --
True: The variables representing the derivatives are eliminated
via the collocation equations and are thus not a part of the NLP.
False: The variables representing the derivatives are kept as NLP
variables and the collocation equations enter as constraints.
Currently does not work in combination with either Mayer type cost
functions or DAE initial equations containing state derivatives.
Type: bool
Default: False
eliminate_cont_var --
True: Let the same variables represent both the values of the
states at the start of each element and the end of the previous
element.
False: Create extra variables for the states at the start of each
element and then constrain them to be equal to the corresponding
variable at the end of the previous element for continuity.
Type: bool
Default: False
init_traj --
Variable trajectory data used for initialization of the
optimization problem.
Type: None or jmodelica.io.DymolaResultTextual
Default: None
parameter_estimation_data --
Parameter estimation data used for solving parameter estimation
problems.
Type: None or jmodelica.optimization.parameter_estimation_data
Default: None
exact_hessian --
If True, the exact Hessian of the Lagrangian function is used.
Exact Hessians is currently not fully supported by CasADi for MX
graphs, see https://sourceforge.net/apps/trac/casadi/ticket/164.
It works, but it's inefficient and will lead to very slow
initialization times.
Type: bool
Default: True
Options are set by using the syntax for dictionaries:
>>> opts = my_model.optimize_options()
>>> opts['n_e'] = 100
In addition, CasADi options can be provided in the options CasADi_options_F, CasADi_options_G and CasADi_options_L for the NLP objective, constraint and Lagrangian functions respectively. For a complete list of CasADi options, please consult the CasADi documentation.
See http://casadi.sourceforge.net/api/html/d2/d58/classCasADi_1_1SXFunction.html for SX and expanded_MX graphs and http://casadi.sourceforge.net/api/html/dc/d0b/classCasADi_1_1MXFunction.html for MX graphs.
CasADi options are set using the syntax for dictionaries:
>>> opts['CasADi_options_G']['numeric_jacobian'] = True
IPOPT options can be provided in the option IPOPT_options. For a complete list of IPOPT options, please consult the IPOPT documentation available at http://www.coin-or.org/Ipopt/documentation/).
Some commonly used IPOPT options are provided by default:
max_iter --
Maximum number of iterations.
Type: int
Default: 3000
derivative_test --
Check the correctness of the NLP derivatives. Valid values are
'none', 'first-order', 'second-order', 'only-second-order'.
Type: str
Default: 'none'
IPOPT options are set using the syntax for dictionaries:
>>> opts['IPOPT_options']['max_iter'] = 200
Bases: jmodelica.algorithm_drivers.JMResultBase
A JMResultBase object with the additional attributes times and h_opt.
Attributes:
times --
A dictionary with the keys 'sol', 'init' and 'tot'.
times['sol'] is the (clock) time spent solving the NLP (total IPOPT
time).
times['init'] is the time spent creating the NLP.
times['tot'] is the sum of times['sol'] and times['init'].
Type: dict
h_opt --
An array with the optimized element lengths.
The element lengths are only optimized (and stored in a class
instance) if the algorithm option "hs" == free. Otherwise this
attribute is None.
Type: ndarray of floats or None
Bases: jmodelica.algorithm_drivers.OptionBase
Options for optimizing JMU models using a collocation algorithm.
Collocation algorithm options:
n_e --
Number of phases of the finite element mesh.
Default: 50
n_cp --
Number of collocation points in each element.
Default: 3
init_traj --
Variable trajectory data used for initialization of the optimization
problem. The data is represented by an object of the type
jmodelica.io.DymolaResultTextual.
Default: None
Options are set by using the syntax for dictionaries:
>>> opts = my_model.optimize_options()
>>> opts['n_e'] = 100
In addition, IPOPT options can be provided in the option IPOPT_options. For a complete list of IPOPT options, please consult the IPOPT documentation available at http://www.coin-or.org/Ipopt/documentation/).
Some commonly used IPOPT options are provided by default:
max_iter --
Maximum number of iterations.
Default: 3000
derivative_test --
Check the correctness of the NLP derivatives. Valid values are
'none', 'first-order', 'second-order', 'only-second-order'.
Default: 'none'
IPOPT options are set using the syntax for dictionaries:
>>> opts['IPOPT_options']['max_iter'] = 200
Bases: jmodelica.algorithm_drivers.AlgorithmBase
The algorithm is based on orthogonal collocation and relies on the solver IPOPT for solving a non-linear programming problem.
Get an instance of the options class for the CollocationLagrangePolynomialsAlg algorithm, prefilled with default values. (Class method.)
Bases: jmodelica.algorithm_drivers.OptionBase
Options for optimizing JMU models using a collocation algorithm.
Collocation algorithm options:
n_e --
Number of elements of the finite element mesh.
Default: 50
n_cp --
Number of collocation points in each element. Values between 1 and
10 are supported
Default: 3
hs --
A vector containing n_e elements representing the finite element
lengths. The sum of all element should equal to 1.
Default: numpy.ones(n_e)/n_e (Uniform mesh)
blocking_factors --
A vector of blocking factors. Blocking factors are specified by a
vector of integers, where each entry in the vector corresponds to
the number of elements for which the control profile should be kept
constant. For example, the blocking factor specification [2,1,5]
means that u_0=u_1 and u_3=u_4=u_5=u_6=u_7 assuming that the number
of elements is 8. Notice that specification of blocking factors
implies that controls are present in only one collocation point
(the first) in each element. The number of constant control levels
in the optimization interval is equal to the length of the blocking
factor vector. In the example above, this implies that there are
three constant control levels. If the sum of the entries in the
blocking factor vector is not equal to the number of elements, the
vector is normalized, either by truncation (if the sum of the
entries is larger than the number of element) or by increasing the
last entry of the vector. For example, if the number of elements is
4, the normalized blocking factor vector in the example is [2,2].
If the number of elements is 10, then the normalized vector is
[2,1,7].
Default: None
init_traj --
Variable trajectory data used for initialization of the optimization
problem. The data is represented by an object of the type
jmodelica.io.DymolaResultTextual.
Default: None
result_mode --
Specifies the output format of the optimization result.
- 'default' gives the the optimization result at the collocation
points.
- 'element_interpolation' computes the values of the variable
trajectories using the collocation interpolation polynomials. The
option 'n_interpolation_points' is used to specify the number of
evaluation points within each finite element.
- 'mesh_interpolation' computes the values of the variable
trajectories at points defined by the option 'result_mesh'.
Default: 'default'
n_interpolation_points --
Number of interpolation points in each finite element if the result
reporting option result_mode is set to 'element_interpolation'.
Default: 20
result_mesh --
A vector of time points at which the the optimization result is
computed. This option is used if result_mode is set to
'mesh_interpolation'.
Default: None
result_file_name --
Specifies the name of the file where the optimization result is
written. Setting this option to an empty string results in a default
file name that is based on the name of the optimization class.
Default: Empty string
result_format --
Specifies in which format to write the result. Currently
only textual mode is supported.
Default: 'txt'
write_scaled_result --
Write the scaled optimization result if set to true. This option is
only applicable when automatic variable scaling is enabled. Only for
debugging use.
Default: False.
Options are set by using the syntax for dictionaries:
>>> opts = my_model.optimize_options()
>>> opts['n_e'] = 100
In addition, IPOPT options can be provided in the option IPOPT_options. For a complete list of IPOPT options, please consult the IPOPT documentation available at http://www.coin-or.org/Ipopt/documentation/).
Some commonly used IPOPT options are provided by default:
max_iter --
Maximum number of iterations.
Default: 3000
derivative_test --
Check the correctness of the NLP derivatives. Valid values are
'none', 'first-order', 'second-order', 'only-second-order'.
Default: 'none'
IPOPT options are set using the syntax for dictionaries:
>>> opts['IPOPT_options']['max_iter'] = 200
Bases: exceptions.Exception
Exception raised when an algorithm options argument is encountered that is not valid.
Bases: exceptions.Exception
Exception raised when a solver argument is encountered that does not exist.
Bases: jmodelica.algorithm_drivers.AlgorithmBase
Initialization of a model using Ipopt.
Get an instance of the options class for the IpoptInitializationAlg algorithm, prefilled with default values. (Class method.)
Bases: jmodelica.algorithm_drivers.OptionBase
Options for the IPOPT-based initialization algorithm.
Initialization algorithm options:
stat --
Solve a static optimization problem.
Default: False
result_file_name --
Specifies the name of the file where the optimization result is
written. Setting this option to an empty string results in a default
file name that is based on the name of the optimization class.
Default: Empty string
result_format --
Specifies in which format to write the result. Currently only
textual mode is supported.
Default: 'txt'
write_scaled_result --
Set this parameter to True to write the result to file without
taking scaling into account. If the value of scaled is False, then
the variable scaling factors of the model are used to reproduced the
unscaled variable values.
Default: False
Options are set by using the syntax for dictionaries:
>>> opts = my_model.initialize_options()
>>> opts['stat'] = True
In addition, IPOPT options can be provided in the option IPOPT_options. For a complete list of IPOPT options, please consult the IPOPT documentation available at http://www.coin-or.org/Ipopt/documentation/).
Some commonly used IPOPT options are provided by default:
max_iter --
Maximum number of iterations.
Default: 3000
derivative_test --
Check the correctness of the NLP derivatives. Valid values are
'none', 'first-order', 'second-order', 'only-second-order'.
Default: 'none'
IPOPT options are set using the syntax for dictionaries:
>>> opts['IPOPT_options']['max_iter'] = 200
Bases: jmodelica.algorithm_drivers.ResultBase
Property for accessing the result matrix.
Returns the column number in the data matrix where the values of the variable are stored.
Parameters:
name --
Name of the variable/parameter/constant.
Returns:
The column number.
Returns True if the given name corresponds to a time-varying variable.
Parameters:
name --
Name of the variable/parameter/constant.
Returns:
True if the variable is time-varying.
Returns the variable names in the result file.
Bases: jmodelica.algorithm_drivers.AlgorithmBase
Initialization using a solver of non-linear eq-systems.
Get an instance of the options class for the KInitSolveAlg algorithm, prefilled with default values. (Class method.)
Bases: jmodelica.algorithm_drivers.OptionBase
Options for the initialization of a JMU using the KInitSolve algorithm based on the KINSOL wrapper in the assimulo package.
KInitSolve options:
use_constraints --
Boolean set to True if constraints are to be used. If set to False,
the initialization will not be constraind even if constraints are
supplied by the user. If set to True but constraints are not
supplied please see the documentation of constraints below.
Default: False
constraints --
Numpy.array that should be of same size as the number of variables.
The array contains numbers specifying what type of constraint to use
for each variable. The array contains the following number in the
ith position:
0.0 - no constraint on x[i]
1.0 - x[i] greater or equal than 0.0
-1.0 - x[i] lesser or equal than 0.0
2.0 - x[i] greater than 0.0
-2.0 - x[i] lesser than 0.0
If no constraints are supplied but use_constraints are set to True
the solver will 'guess' constraints basically meaning that the sign
of a variable is kept the same as the sign of the initial guess for
the variable.
Default: None
result_file_name --
A string containing the name of the file the results should be
written to. If not specified the name of the model will be used.
Default: ''
result_format --
A string specifying the format of the output file. So far only
'.txt' is supported
Default: '.txt'
The solver used by kinitsol is KINSOL, the options for KINSOL is passed in the dictionary KINSOL_options. The options are listed below:
Integer regulationg the level of information output from KINSOL. Must be set to one of:
0: no information displayed. 1: for each nonlinear iteration display the following information:
- the scaled Euclidean ℓ2 norm of the residual evaluated at the current iterate
- the scaled norm of the Newton step
- the number of function evaluations performed so far.
- 2: display level 1 output and the following values for each iteration:
- the 2-norm and infinitynorm of the scaled residual at the current iterate
- 3: display level 2 output plus additional values used by the global strategy,
- and statistical information for the linear solver.
Default: 0
Bases: dict
Base class for an algorithm option class.
All algorithm option classes should extend this class.
This class extends the dict class overriding __init__, __setitem__, update and setdefault methods with the purpose of offering a key check for the extending classes.
The extending class can define a set of keys and default values by overriding __init__ or when instantiating the extended class and thereby not allow any other keys to be added to the dict.
- Example overriding __init__:
>> opts = MyOptionsClass() >> opts[‘def1’] = 3 // ok >> opts.update({‘def2’:4}) // ok >> opts[‘def3’]= 5 // not ok
- Example setting defaults in constructor:
class MyOptionsClass(OptionBase):pass
>> opts = MyOptionsClass(def1=1, def2=2) >> opts[‘def1’] = 3 // ok >> opts.update({‘def2’:4}) // ok >> opts[‘def3’]= 5 // not ok
>> opts2 = MyOptionsClass() // this class has no restrictions on keys >> opts2[‘def5’] = ‘hello’ //ok
Bases: object
Base class for an algorithm result. All algorithms used in any of the high-level functions should return an object which extends this class.
Property for accessing the model that was used in the algorithm.
Property for accessing he options object holding the options used in the algorithm.
Property for accessing the result data matrix that was created in the algorithm.
Property for accessing the name of the result file created in the algorithm.
Property for accessing the solver that was used in the algorithm.