Unification of command line options among multiple runtimes

[Rüdiger Franke]

The C runtime has a lot of command line options. The Cpp runtime has less command line options. Typically the names and the syntax are different. C options are long names that start with one dash and lower case character; Cpp options are either long names that start with two dashes or short (one character) that starts with one dash.

Since OpenModelica 1.9.4 the short Cpp options were changed to upper case letters. This way they are unique, because the C runtime uses no upper case letters.

This proposal is that the C runtime introduces short versions of the most important command line options as well. The short versions should be the same among all runtimes, while the long versions may be specific.

The proposed short options are:

-S arg	simulation start time
-E arg	simulation end time
-H arg	simulation step size
-G arg	number of intervals in equidistant grid
-I arg	integration solver method
-L arg	linear solver method
-N arg	nonlinear solver method
-C	continue if nonlinear solver does not converge
-T arg	integration solver tolerance
-V arg	log settings (all, events, ls, nls, states, warning, discard, error, fatal, pending -- cf. FMI 2 spec)
-O arg	output writing (all, step, none) for all steps and events or only steps or nothing
-P arg	simulation results output format (mat or csv)
-A arg	abort after arg seconds
-F arg	name of results file
-M arg	path to Modelica Standard Library
-R arg	path to simulation runtime libs

[Lennart Ochel]

I think this is a good idea. Any comments?

[Lennart Ochel]

This is a complete list of all command line options available in c runtime. I tried to match the proposed short options from above. However, there are a couple of options which are not available or handled different in c runtime.

-abortSlowSimulation		aborts if the simulation chatters
-alarm value	-A	aborts after the given number of seconds (0 disables)
-clock value		selects the type of clock to use -clock=RT, -clock=CYC or -clock=CPU
-cpu		dumps the cpu-time into the result file
-csvOstep value		value specifies csv-files for debuge values for optimizer step
-daeMode		flag to let the integrator use daeResiduals
-embeddedServer value		enables an embedded server. Valid values: none, opc-da [broken], opc-ua [experimental], or the path to a shared object.
-emit_protected		emits protected variables to the result-file
-f value		value specifies a new setup XML file to the generated simulation code
-help value		get detailed information that specifies the command-line flag
-idaMaxErrorTestFails value		value specifies the maximum number of error test failures in attempting one step. The default value is 7.
-idaMaxNonLinIters value		value specifies the maximum number of nonlinear solver iterations at one step. The default value is 3.
-idaMaxConvFails value		value specifies the maximum number of nonlinear solver convergence failures at one step. The default value is 10.
-idaNonLinConvCoef value		value specifies the safety factor in the nonlinear convergence test. The default value is 0.33.
-idaLS value		selects the linear solver used by ida
-idaSensitivity		flag to add sensitivity information to the result files
-ignoreHideResult		ignore HideResult=true annotation
-iif value		value specifies an external file for the initialization of the model
-iim value		value specifies the initialization method
-iit value		[double] value specifies a time for the initialization of the model
-ils value		[int] default: 1
-initialStepSize value		value specifies an initial stepsize for the dassl solver
-csvInput value		value specifies an csv-file with inputs for the simulation/optimization of the model
-exInputFile value		value specifies an external file with inputs for the simulation/optimization of the model
-stateFile value		value specifies an file with states start values for the optimization of the model
-ipopt_hesse value		value specifies the hessian for Ipopt
-ipopt_init value		value specifies the initial guess for optimization
-ipopt_jac value		value specifies the jacobian for Ipopt
-ipopt_max_iter value		value specifies the max number of iteration for ipopt
-ipopt_warm_start value		value specifies lvl for a warm start in ipopt: 1,2,3,...
-jacobian value		selects the type of the jacobians that is used for the integrator.
-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		value specifies the log format of the executable. -logFormat=text (default) or -logFormat=xml
-ls value	-L	value specifies the linear solver method (default: lapack, totalpivot (fallback))
-ls_ipopt value		value specifies the linear solver method for ipopt
-lss value		value specifies the linear sparse solver method (default: umfpack)
-lssMaxDensity value		[double (default 0.2)] value specifies the maximum density for using a linear sparse solver
-lssMinSize value		[int (default 4001)] value specifies the minimum system size for using a linear sparse solver
-lv value	-V	[string list] value specifies the logging level
-mbi value		[int (default 0)] value specifies the maximum number of bisection iterations for state event detection or zero for default behavior
-mei value		[int (default 20)] value specifies the maximum number of event iterations
-maxIntegrationOrder value		value specifies maximum integration order, used by dassl solver
-maxStepSize value	-H	value specifies maximum absolute step size, used by dassl solver
-measureTimePlotFormat value		value specifies the output format of the measure time functionality
-newtonFTol value		[double (default 1e-12)] tolerance respecting residuals for updating solution vector in Newton solver
-newtonXTol value		[double (default 1e-12)] tolerance respecting newton correction (delta_x) for updating solution vector in Newton solver
-newton value		value specifies the damping strategy for the newton solver
-nls value	-N	value specifies the nonlinear solver
-nlsInfo		outputs detailed information about solving process of non-linear systems into csv files.
-noemit		do not emit any results to the result file
-noEquidistantTimeGrid		stores results not in equidistant time grid as given by stepSize or numberOfIntervals, instead the variable step size of dassl is used.
-noEquidistantOutputFrequency value		value controls the output frequency in noEquidistantTimeGrid mode
-noEquidistantOutputTime value		value controls the output time point in noEquidistantOutputTime mode
-noEventEmit		do not emit event points to the result file
-noRestart		flag deactivates the restart of dassl/ida after an event is performed.
-noRootFinding		flag deactivates the internal root finding procedure of dassl/ida.
-noSuppressAlg		flag to not suppress algebraic variables in the local error test of ida solver in daeMode
-optDebugJac value		value specifies the number of iter from the dyn. optimization, which will be debuge, creating *csv and *py file
-optimizerNP value		value specifies the number of points in a subinterval
-optimizerTimeGrid value		value specifies external file with time points.
-output value		output the variables a, b and c at the end of the simulation to the standard output
-override value		override the variables or the simulation settings in the XML setup file
-overrideFile value		will override the variables or the simulation settings in the XML setup file with the values from the file
-port value		value specifies the port for simulation status (default disabled)
-r value	-F	value specifies a new result file than the default Model_res.mat
-rt value		value specifies the scaling factor for real-time synchronization (0 disables)
-s value	-I	value specifies the solver
-steps		dumps the number of integration steps into the result file
-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

[Rüdiger Franke]

We might reduce the list of common options. The option -M for MSL path is not so important. Others, like -S and -E for start and end time are important.

Take the call of OMEdit as examples / use case for common arguments:

MyModel -port=52924 -logFormat=xml -override=startTime=0,stopTime=1,stepSize=0.002,tolerance=0.0001,solver=dassl,outputFormat=mat,variableFilter=.* -r=MyModel_res.mat -jacobian=coloredNumerical -w -lv=LOG_STATS

It appears that many options appear under -override. The call could look like:

MyModel -S 0 -E 1 -H 0.002 -T 0.0001 -I dassl -P mat -F MyModel_res.mat

Some options are not covered, like -port and -logFormat. Others might me skipped as they are default, like variableFilter=.*.

It seems we need to iterate a bit to find a useful common subset.

[Martin Sjölund]

If we have common short options, we need common long names as well. I really dislike flags like -S 0 -E 1 since you need to check the documentation to see what the flag does. --startTime=0 --stopTime=1 is much easier to read.

[Lennart Ochel]

I see good reasons to change the command line options. For example, the -override flag is rather bad. It should get split up to just handle overrides of variables and parameters and there should be a new option to override simulation settings (e.g. --startTime=0 --stopTime=1). However, this would break backwards compatibility. I suggest discussing this within the next dev meeting.

[Rüdiger Franke]

Even better if a bigger change is introduced, provided the result will be better than what we have today. What is the right way of writing options? Modelica experiment annotations use StartTime=0, StopTime=1. You propose --startTime=0, --stopTime=1. Long program options are typically written as --start-time=0, --stop-time=1?

[Martin Sjölund]

Milestone moved to 1.12.0 due to 1.11.0 already being released.

[Francesco Casella]

Milestone moved to 1.13.0 due to 1.12.0 already being released.

[Francesco Casella]

Rescheduled to 1.14.0 after 1.13.0 releasee

[Francesco Casella]

Releasing 1.14.0 which is stable and has many improvements w.r.t. 1.13.2. This issue is rescheduled to 1.16.0

[Francesco Casella]

Retargeted to 1.17.0 after 1.16.0 release

[Francesco Casella]

Retargeted to 1.18.0 because of 1.17.0 timed release.

[Francesco Casella]

Ticket retargeted after milestone closed