Small Overview of Simulation Flags¶

This chapter contains a short overview of simulation flags as well as additional details of the numerical integration methods.

OpenModelica (C-runtime) Simulation Flags¶

The simulation executable takes the following flags:

-abortSlowSimulation: Aborts if the simulation chatters.

-alarm=value or -alarm value: Aborts after the given number of seconds (default=0 disables the alarm).

-clock=value or -clock value

Selects the type of clock to use. Valid options include:

RT (monotonic real-time clock)
CYC (cpu cycles measured with RDTSC)
CPU (process-based CPU-time)

-cpu: Dumps the cpu-time into the result file using the variable named $cpuTime

-csvOstep=value or -csvOstep value: Value specifies csv-files for debug values for optimizer step

-daeMode: Enables daeMode simulation if the model was compiled with the omc flag --daeMode and ida method is used.

-deltaXLinearize=value or -deltaXLinearize value value specifies the delta x value for numerical differentiation used by linearization. The default value is sqrt(DBL_EPSILON*2e1).

-deltaXSolver=value or -deltaXSolver value value specifies the delta x value for numerical differentiation used by integration method. The default values is sqrt(DBL_EPSILON).

-embeddedServer=value or -embeddedServer value

Enables an embedded server. Valid values:

none - default, run without embedded server
opc-da - [broken] run with embedded OPC DA server (WIN32 only, uses proprietary OPC SC interface)
opc-ua - [experimental] run with embedded OPC UA server (TCP port 4841 for now; will have its own configuration option later)
filename - path to a shared object implementing the embedded server interface (requires access to internal OMC data-structures if you want to read or write data)

-embeddedServerPort=value or -embeddedServerPort value: Value specifies the port number used by the embedded server. The default value is 4841.

-emit_protected: Emits protected variables to the result-file.

-f=value or -f value: Value specifies a new setup XML file to the generated simulation code.

-help=value or -help value: Get detailed information that specifies the command-line flag For example, -help=f prints detailed information for command-line flag f.

-homAdaptBend=value or -homAdaptBend value: maximum trajectory bending to accept the homotopy step

-homHEps=value or -homHEps value: tolerance respecting residuals for the homotopy H-function

-homMaxLambdaSteps=value or -homMaxLambdaSteps value: maximum lambda steps allowed to run the homotopy path

-homMaxNewtonSteps=value or -homMaxNewtonSteps value: maximum newton steps in the homotopy corrector step

-homMaxTries=value or -homMaxTries value: maximum number of tries for one homotopy lambda step

-homotopyOnFirstTry: If the model contains the homotopy operator, directly use the homotopy method to solve the initialization problem. Without this flag, the solver first tries to solve the initialization problem without homotopy and only uses homotopy as fallback option.

-homTauDecFac=value or -homTauDecFac value: decrease homotopy step size tau by this factor if tau is too big in the homotopy corrector step

-homTauDecFacPredictor=value or -homTauDecFacPredictor value: decrease homotopy step size tau by this factor if tau is too big in the homotopy predictor step

-homTauIncFac=value or -homTauIncFac value: increase homotopy step size tau by this factor if tau is too small in the homotopy corrector step

-homTauIncThreshold=value or -homTauIncThreshold value: increase the homotopy step size tau if bend < homAdaptBend/homTauIncThreshold

-homTauMax=value or -homTauMax value: maximum homotopy step size tau for the homotopy process

-homTauMin=value or -homTauMin value: minimum homotopy step size tau for the homotopy process

-homTauStart=value or -homTauStart value: homotopy step size tau at the beginning of the homotopy process

-idaMaxErrorTestFails=value or -idaMaxErrorTestFails value: value specifies the maximum number of error test failures in attempting one step. The default value is 7.

-idaMaxNonLinIters=value or -idaMaxNonLinIters value: value specifies the maximum number of nonlinear solver iterations at one step. The default value is 3.

-idaMaxConvFails=value or -idaMaxConvFails value: value specifies the maximum number of nonlinear solver convergence failures at one step. The default value is 10.

-idaNonLinConvCoef=value or -idaNonLinConvCoef value: value specifies the safety factor in the nonlinear convergence test. The default value is 0.33.

-idaLS=value or -idaLS value: Value specifies the linear solver of the ida integration method. Valid values: * klu - default, fast sparse linear solver * dense - dense linear solver, sundials default method * spgmr - sparse iterative linear solver based on generalized minimal residual method, convergance is not guaranteed, sundials method * spbcg - sparse iterative linear solver based on biconjugate gradient method, convergance is not guaranteed, sundials method * spgmr - sparse iterative linear solver based on transpose free quasi-minimal residual method, convergance is not guaranteed, sundials method

-idaSensitivity: Enables sensitivity analysis with respect to parameters if the model is compiled with omc flag --calculateSensitivities.

-ignoreHideResult: Emits also variables with HideResult=true annotation.

-iif=value or -iif value: Value specifies an external file for the initialization of the model.

-iim=value or -iim value

Value specifies the initialization method. Following options are available: 'symbolic' (default) and 'none'.

none (sets all variables to their start values and skips the initialization process)
symbolic (solves the initialization problem symbolically - default)

-iit=value or -iit value: Value [Real] specifies a time for the initialization of the model.

-ils=value or -ils value: Value specifies the number of steps for homotopy method (required: -iim=symbolic). The value is an Integer with default value 4.

-impRKOrder=value or -impRKOrder value: Value specifies the integration order of the implicit Runge-Kutta method. Valid values: 1 to 6. Default order is 5.

-impRKLS=value or -impRKLS value: Selects the linear solver of the integration methods: impeuler, trapezoid and imprungekuta * iterativ - default, sparse iterativ linear solver with fallback case to dense solver * dense - dense linear solver, sundials default method

-initialStepSize=value or -initialStepSize value: Value specifies an initial step size, used by the methods: dassl, ida

-csvInput=value or -csvInput value: Value specifies an csv-file with inputs for the simulation/optimization of the model

-exInputFile=value or -exInputFile value: Value specifies an external file with inputs for the simulation/optimization of the model.

-stateFile=value or -stateFile value: Value specifies an file with states start values for the optimization of the model.

-ipopt_hesse=value or -ipopt_hesse value: Value specifies the hessematrix for Ipopt(OMC, BFGS, const).

-ipopt_init=value or -ipopt_init value: Value specifies the initial guess for optimization (sim, const).

-ipopt_jac=value or -ipopt_jac value: Value specifies the Jacobian for Ipopt(SYM, NUM, NUMDENSE).

-ipopt_max_iter=value or -ipopt_max_iter value: Value specifies the max number of iteration for ipopt.

-ipopt_warm_start=value or -ipopt_warm_start value: Value specifies lvl for a warm start in ipopt: 1,2,3,...

-jacobian=value or -jacobian value: Select the calculation method for Jacobian used by the integration method: * coloredNumerical - A dense colored numerical Jacobian, which is default for dassl. Usable with dassl and ida. * internalNumerical - A dense internal numerical Jacobian. Usable with dassl and ida. * coloredSymbolical - A dense colored symbolical Jacobian. Needs omc compiler flag --postOptModules+=generateSymbolicJacobian. Usable with dassl and ida. * numerical - A dense numerical Jacobian. Usable with dassl and ida. * symbolical - A dense symbolical Jacobian. Needs omc compiler flag --postOptModules+=generateSymbolicJacobian. Usable with dassl and ida. * kluSparse - A sparse colored numerical Jacobian, which is default for ida. Usable with ida.

-l=value or -l value: Value specifies a time where the linearization of the model should be performed.

-l_datarec: Emit data recovery matrices with model linearization.

-logFormat=value or -logFormat value

Value specifies the log format of the executable:

text (default)
xml
xmltcp (required -port flag)

-ls=value or -ls value

Value specifies the linear solver method

lapack (method using lapack LU factorization)
lis (method using iterative solver Lis)
klu (method using klu sparse linear solver)
umfpack (method using umfpack sparse linear solver)
totalpivot (method using a total pivoting LU factorization for underdetermination systems)
default (default method - lapack with total pivoting as fallback)

-ls_ipopt=value or -ls_ipopt value: Value specifies the linear solver method for Ipopt, default mumps. Note: Use if you build ipopt with other linear solver like ma27

-lss=value or -lss value: Value specifies the linear sparse solver method

-lssMaxDensity=value or -lssMaxDensity value: Value specifies the maximum density for using a linear sparse solver. The value is a Double with default value 0.2.

-lssMinSize=value or -lssMinSize value: Value specifies the minimum system size for using a linear sparse solver. The value is an Integer with default value 4001.

-lv=value or -lv value

Value (a comma-separated String list) specifies which logging levels to enable. Multiple options can be enabled at the same time.

LOG_DASSL (additional information about dassl solver)
LOG_DASSL_STATES (outputs the states at every dassl call)
LOG_DEBUG (additional debug information)
LOG_DSS (outputs information about dynamic state selection)
LOG_DSS_JAC (outputs jacobian of the dynamic state selection)
LOG_DT (additional information about dynamic tearing)
LOG_DT_CONS (additional information about dynamic tearing (local and global constraints))
LOG_EVENTS (additional information during event iteration)
LOG_EVENTS_V (verbose logging of event system)
LOG_INIT (additional information during initialization)
LOG_IPOPT (information from Ipopt)
LOG_IPOPT_FULL (more information from Ipopt)
LOG_IPOPT_JAC (check jacobian matrix with Ipopt)
LOG_IPOPT_HESSE (check hessian matrix with Ipopt)
LOG_IPOPT_ERROR (print max error in the optimization)
LOG_JAC (outputs the jacobian matrix used by dassl)
LOG_LS (logging for linear systems)
LOG_LS_V (verbose logging of linear systems)
LOG_NLS (logging for nonlinear systems)
LOG_NLS_V (verbose logging of nonlinear systems)
LOG_NLS_HOMOTOPY (logging of homotopy solver for nonlinear systems)
LOG_NLS_JAC (outputs the jacobian of nonlinear systems)
LOG_NLS_JAC_TEST (tests the analytical jacobian of nonlinear systems)
LOG_NLS_RES (outputs every evaluation of the residual function)
LOG_NLS_EXTRAPOLATE (outputs debug information about extrapolate process)
LOG_RES_INIT (outputs residuals of the initialization)
LOG_RT (additional information regarding real-time processes)
LOG_SIMULATION (additional information about simulation process)
LOG_SOLVER (additional information about solver process)
LOG_SOLVER_V (verbose information about the integration process)
LOG_SOLVER_CONTEXT (context information during the solver process)
LOG_SOTI (final solution of the initialization)
LOG_STATS (additional statistics about timer/events/solver)
LOG_STATS_V (additional statistics for LOG_STATS)
LOG_UTIL (???)
LOG_ZEROCROSSINGS (additional information about the zerocrossings)

-mbi=value or -mbi value: value specifies the maximum number of bisection iterations for state event detection or zero for default behavior

-mei=value or -mei value: Value specifies the maximum number of event iterations. The value is an Integer with default value 20.

-maxIntegrationOrder=value or -maxIntegrationOrder value: Value specifies maximum integration order, used by the methods: dassl, ida.

-maxStepSize=value or -maxStepSize value: Value specifies maximum absolute step size, used by the methods: dassl, ida.

-measureTimePlotFormat=value or -measureTimePlotFormat value

Value specifies the output format of the measure time functionality

svg
jpg
ps
gif
...

-newtonFTol=value or -newtonFTol value: Tolerance respecting residuals for updating solution vector in Newton solver. Solution is accepted if the (scaled) 2-norm of the residuals is smaller than the tolerance newtonFTol and the (scaled) newton correction (delta_x) is smaller than the tolerance newtonXTol. The value is a Double with default value 1e-12.

-newtonMaxStepFactor=value or -newtonMaxStepFactor value: Maximum newton step factor mxnewtstep = maxStepFactor * norm2(xScaling). Used currently only by kinsol.

-newtonXTol=value or -newtonXTol value: Tolerance respecting newton correction (delta_x) for updating solution vector in Newton solver. Solution is accepted if the (scaled) 2-norm of the residuals is smaller than the tolerance newtonFTol and the (scaled) newton correction (delta_x) is smaller than the tolerance newtonXTol. The value is a Double with default value 1e-12.

-newton=value or -newton value

Value specifies the damping strategy for the newton solver.

damped (Newton with a damping strategy)
damped2 (Newton with a damping strategy 2)
damped_ls (Newton with a damping line search)
damped_bt (Newton with a damping backtracking and a minimum search via golden ratio method)
pure (Newton without damping strategy)

-nls=value or -nls value

Value specifies the nonlinear solver:

hybrid
kinsol
newton
mixed
hybrid (Modification of the Powell hybrid method from minpack - former default solver)
kinsol (sundials/kinsol - prototype implementation)
newton (Newton Raphson - prototype implementation)
homotopy (Damped Newton solver if failing case fixed-point and Newton homotopies are tried.)
mixed (Mixed strategy. First the homotopy solver is tried and then as fallback the hybrid solver.)

-nlsInfo: Outputs detailed information about solving process of non-linear systems into csv files.

-nlsLS=value or -nlsLS value: Value specifies the linear solver used by the non-linear solver: * totalpivot * lapack (default) * klu

-nlssMaxDensity=value or -nlssMaxDensity value: Value specifies the maximum density for using a non-linear sparse solver. The value is a Double with default value 0.2.

-nlssMinSize=value or -nlssMinSize value: Value specifies the minimum system size for using a non-linear sparse solver. The value is an Integer with default value 10001.

-noemit: Do not emit any results to the result file.

-noEquidistantTimeGrid: Output the internal steps given by dassl/ida instead of interpolating results into an equidistant time grid as given by stepSize or numberOfIntervals.

-noEquidistantOutputFrequency=value or -noEquidistantOutputFrequency value: Integer value n controls the output frequency in noEquidistantTimeGrid mode and outputs every n-th time step

-noEquidistantOutputTime=value or -noEquidistantOutputTime value: Real value timeValue controls the output time point in noEquidistantOutputTime mode and outputs every time>=k*timeValue, where k is an integer

-noEventEmit: Do not emit event points to the result file.

-noRestart: Disables the restart of the integration method after an event is performed, used by the methods: dassl, ida

-noRootFinding: Disables the internal root finding procedure of methods: dassl and ida.

-noScaling: Disables scaling for the variables and the residuals in the algebraic nonlinear solver kinsol.

-noSuppressAlg: flag to not suppress algebraic variables in the local error test of the ida solver in daeMode. In general, the use of this option is discouraged when solving DAE systems of index 1, whereas it is generally encouraged for systems of index 2 or more.

-optDebugJac=value or -optDebugJac value: Value specifies the number of iterations from the dynamic optimization, which will be debugged, creating .csv and .py files.

-optimizerNP=value or -optimizerNP value: Value specifies the number of points in a subinterval. Currently supports numbers 1 and 3.

-optimizerTimeGrid=value or -optimizerTimeGrid value: Value specifies external file with time points.

-output=value or -output value: Output the variables a, b and c at the end of the simulation to the standard output: time = value, a = value, b = value, c = value

-override=value or -override value: Override the variables or the simulation settings in the XML setup file For example: var1=start1,var2=start2,par3=start3,startTime=val1,stopTime=val2

-overrideFile=value or -overrideFile value: Will override the variables or the simulation settings in the XML setup file with the values from the file. Note that: -overrideFile CANNOT be used with -override. Use when variables for -override are too many. overrideFileName contains lines of the form: var1=start1

-port=value or -port value: Value specifies the port for simulation status (default disabled).

-r=value or -r value: Value specifies the name of the output result file. The default file-name is based on the model name and output format. For example: Model_res.mat.

-rt=value or -rt value: Value specifies the scaling factor for real-time synchronization (0 disables). A value > 1 means the simulation takes a longer time to simulate.

-s=value or -s value

Value specifies the integration method.

euler - Euler - explicit, fixed step size, order 1
heun - Heun's method - explicit, fixed step, order 2
rungekutta - classical Runge-Kutta - explicit, fixed step, order 4
impeuler - Euler - implicit, fixed step size, order 1
trapezoid - trapezoidal rule - implicit, fixed step size, order 2
imprungekutta - Runge-Kutta methods based on Radau and Lobatto IIA - implicit, fixed step size, order 1-6(selected manually by flag -impRKOrder)
irksco - own developed Runge-Kutta solver - implicit, step size control, order 1-2
dassl - default solver - BDF method - implicit, step size control, order 1-5
ida - SUNDIALS IDA solver - BDF method with sparse linear solver - implicit, step size control, order 1-5
rungekuttaSsc - Runge-Kutta based on Novikov (2016) - explicit, step size control, order 4-5 [experimental]
symSolver - symbolic inline Solver [compiler flag +symSolver needed] - fixed step size, order 1
symSolverSsc - symbolic implicit Euler with step size control [compiler flag +symSolver needed] - step size control, order 1
qss - A QSS solver [experimental]
optimization - Special solver for dynamic optimization

-steps: dumps the number of integration steps into the result file

-steadyState: Aborts the simulation if steady state is reached.

-steadyStateTol=value or -steadyStateTol value: This relative tolerance is used to detect steady state: max(|d(x_i)/dt|/nominal(x_i)) < steadyStateTol

-keepHessian=value or -keepHessian value: Value specifies the number of steps, which keep Hessian matrix constant.

-w: Shows all warnings even if a related log-stream is inactive.

Integration Methods¶

This section contains additional information about the different integration methods in OpenModelica, selected by the method flag of the simulate command or the -s simflag.

dassl¶

Default integration method in OpenModelica. Adams Moulton; the default uses a colored numerical Jacobian and interval root finding. To change settings, use simulation flags such as dasslJacobian, dasslNoRootFinding, dasslNoRestart, initialStepSize, maxStepSize, maxIntegrationOrder, noEquidistantTimeGrid.

Order:	1-5
Step Size Control:	true
Order Control:	true
Stability Region:	variable; depend from order

euler¶

Explicit Euler.

Order:	1
Step Size Control:	false
Order Control:	false
Stability Region:	\|(1,0) Padé \| ≤ 1

rungekutta¶

Classical Runge-Kutta method.

Order:	4
Step Size Control:	false
Order Control:	false
Stability Region:	\|(4,0) Padé \| ≤ 1

radau1¶

Radau IIA with one point.

Order:	1
Step Size Control:	false
Order Control:	false
Stability Region:	\|(0,1) Padé \| ≤ 1

radau3¶

Radau IIA with two points.

Order:	3
Step Size Control:	false
Order Control:	false
Stability Region:	\|(1,2) Padé \| ≤ 1

radau5¶

Radau IIA with three points.

Order:	5
Step Size Control:	false
Order Control:	false
Stability Region:	\|(2,3) Padé \| ≤ 1

lobatto2¶

Lobatto IIIA with two points.

Order:	2
Step Size Control:	false
Order Control:	false
Stability Region:	\|(2,2) Padé \| ≤ 1

lobatto4¶

Lobatto IIIA with three points.

Order:	4
Step Size Control:	false
Order Control:	false
Stability Region:	\|(3,3) Padé \| ≤ 1

lobatto6¶

Lobatto IIIA with four points.

Order:	6
Step Size Control:	false
Order Control:	false
Stability Region:	\|(4,4) Padé \| ≤ 1

Notes¶

Simulation flags maxStepSize and maxIntegrationOrder specifiy maximum absolute step size and maximum integration order used by the dassl solver.

General step size without control $\approx \cfrac{\mbox{stopTime} - \mbox{startTime}}{\mbox{numberOfIntervals}}$ . Events change the step size (see Modelica spec 3.3 p. 88).

For (a,b) Padé see wikipedia.