Changeset d2c4b37c in OpenModelica

Timestamp:

2021-08-31T12:33:50+02:00 (3 years ago)

Author:

Mahder Gebremedhin <mahder.gebremedhin@…>

Children:

8749b7da

Parents:

c28db79

git-author:

Mahder Gebremedhin <mahder.gebremedhin@…> (08/31/21 12:10:51)

git-committer:

Mahder Gebremedhin <mahder.gebremedhin@…> (08/31/21 12:33:50)

Message:

Add description of sim exe flag repetition rules.

Files:

• OMCompiler/SimulationRuntime/c/simulation/options.c (modified) (3 diffs)
• OMCompiler/SimulationRuntime/c/util/simulation_options.c (modified) (2 diffs)
• doc/UsersGuide/source/simulationflags.rst (modified) (1 diff)

OMCompiler/SimulationRuntime/c/simulation/options.c

@@ -114 +114 @@
         // Flag is already specified earlier. Check repetition policy.
         else if(!handle_repeated_flag(j)) {
-          // repetition is invlaid for this Flag
+          // repetition is invalid for this Flag
           return 1;
         }
@@ -136 +136 @@
         // Option is already specified earlier. Check repetition policy.
         else if(!handle_repeated_option(j, argv+i, 0 /*Not sticky*/)) {
-          // repetition is invlaid for this option
+          // repetition is invalid for this option
           return 1;
         }
@@ -160 +160 @@
         // Option is already specified earlier. Check repetition policy.
         else if (!handle_repeated_option(j, argv+i, 1 /*Sticky*/)) {
-          // repetition is invlaid for this option
+          // repetition is invalid for this option
           return 1;
         }

OMCompiler/SimulationRuntime/c/util/simulation_options.c

@@ -222 +222 @@
   /* FLAG_LSS_MAX_DENSITY */              "[double (default 0.2)] value specifies the maximum density for using a linear sparse solver",
   /* FLAG_LSS_MIN_SIZE */                 "[int (default " EXPANDSTRING(DEFAULT_FLAG_LSS_MIN_SIZE) ")] value specifies the minimum system size for using a linear sparse solver",
-  /* FLAG_LV */                           "[string list] value specifies the logging level",
+  /* FLAG_LV */                           "[string list] value specifies the logging level. This flag is allowed to be repeated with REPLACE policy.",
   /* FLAG_LV_TIME */                      "[double list] specifying time interval to allow loging in",
   /* FLAG_MAX_BISECTION_ITERATIONS */     "[int (default 0)] value specifies the maximum number of bisection iterations for state event detection or zero for default behavior",
@@ -444 +444 @@
   /* FLAG_LV */
   "  Value (a comma-separated String list) specifies which logging levels to\n"
-  "  enable. Multiple options can be enabled at the same time.",
+  "  enable. Multiple options can be enabled at the same time.\n"
+  "  Repetition policy: REPLACE.",
   /* FLAG_LV_TIME */
   "  Interval (a comma-separated Double list with two elements) specifies in which\n"

doc/UsersGuide/source/simulationflags.rst

@@ -7 +7 @@
 .. _cruntime-simflags :
 
+
+Repetition of Simulation Flags and Options
+-------------------------------------------------
+Unless it is explicitly specified otherwise, it **is an error** to specify any of the simulation Flags/Options more than once.
+
+
+Repetition policies for specific flags
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+If a Flag/Option is allowed to be repeated, there are three different policies under which it can be processed.
+
+- **Ignore**: Repeated instances of the Flag/Option will be ignored with a warning. For example
+
+    .. code-block:: bash
+
+       $ sim_exe -cx=file1 -cx=file2
+       $ sim_exe -cx=file1
+
+    are equivalent except for the warning issued in the first case.
+
+- **Replace**: Repeated instances of an option will override the current value. (Not applicable for Flags.)
+
+    .. code-block:: bash
+
+       $ sim_exe -cx=file1 -cx=file2
+       $ sim_exe -cx=file2
+
+    are equivalent except for the warning issued in the first case.
+
+
+- **Combine**: Repeated instances of the option's values will be combined as if they were given as values for a single specification of the option. (Not applicable for Flags.)
+
+    .. code-block:: bash
+
+       $ sim_exe -cx=file1 -cx=file2
+       $ sim_exe -cx=file1,file2
+
+    are equivalent except for the warning issued in the first case. Assuming the option supports multiple values.
+
+
+Please check the entry below (or the help messages) for each flag/option to find out if a it is allowed to be repeated and what the specific repetition rules are for it.
+
+Order of flags/options from OpenModelica tools
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+The final order of flag/option specifications are dependent on where they are specified.
+
+If you are running the simulation executable directly then you have complete control of how the flags are ordered as it will be exactly the way you pass them on the command line.
+
+If you are instead using the different OpenModelica tools to perform simulation or if you are using scripts, the order is as follows:
+
+1. Flags/options from annotations in Modelica code are applied.
+
+2. Flags/options specified in the script are applied.
+
+3. Flags/options specified outside the script on the command line are applied.
+
+
+
 OpenModelica (C-runtime) Simulation Flags
 -----------------------------------------