From 9086b291da040804581cab9ef92fcb37c7b57304 Mon Sep 17 00:00:00 2001 From: NikolaiFa Date: Wed, 17 Dec 2025 08:28:39 +0100 Subject: [PATCH] Change wording from state machine "states" to state machine "modes" --- docs/1___overview.adoc | 6 +++--- docs/2_2_common_mechanisms.adoc | 16 ++++++++-------- docs/2_3_common_states.adoc | 26 +++++++++++++------------- docs/2_4_common_schema.adoc | 8 ++++---- docs/2_5_fmu_distribution.adoc | 4 ++-- docs/3_2_model_exchange_api.adoc | 6 +++--- docs/4_2_co-simulation_api.adoc | 10 +++++----- docs/5_2_scheduled_execution_api.adoc | 10 +++++----- docs/7___appendix.adoc | 2 +- 9 files changed, 44 insertions(+), 44 deletions(-) diff --git a/docs/1___overview.adoc b/docs/1___overview.adoc index 7d82cf83f..43c40eb9d 100644 --- a/docs/1___overview.adoc +++ b/docs/1___overview.adoc @@ -321,8 +321,8 @@ Properties that might be additionally needed for trajectory optimization, for ex === How to Read This Document -The core of this document is the description of the state machines and their states for each of the three interface types, each interface type in its own section. -Each state description starts with a brief state's purpose, then the mathematical model in a table linking formulas with C-API functions, and finally descriptions of all allowed functions for this particular state. +The core of this document is the description of the state machines and their modes for each of the three interface types, each interface type in its own section. +Each state machine mode description starts with a brief mode's purpose, then the mathematical model in a table linking formulas with C-API functions, and finally descriptions of all allowed functions for this particular state machine mode. To keep the descriptions brief and redundancy low, <>, which are used by more than one interface type, are described once. @@ -346,4 +346,4 @@ Conventions used in this document: [[VariableTypeExclClock,`{VariableTypeExclClock}`]] * `{VariableTypeExclClock}` is used just like <>, except does not include functions on variable type `fmi3Clock`. -* State machine states are formatted as *bold* link, e.g. <>. +* State machine modes are formatted as *bold* link, e.g. <>. diff --git a/docs/2_2_common_mechanisms.adoc b/docs/2_2_common_mechanisms.adoc index b4546722f..4585c68fb 100644 --- a/docs/2_2_common_mechanisms.adoc +++ b/docs/2_2_common_mechanisms.adoc @@ -12,7 +12,7 @@ The FMU itself does not implement any services to support this.]_ * The following FMI callback functions must not call back into the FMU: ** <>, and ** <>, and - ** <>). + ** <>. + The following callback functions lead to well-defined states and may call FMI functions according to their respective state definitions: @@ -222,9 +222,9 @@ The call failed. The output argument values are undefined and the simulation must not be continued. Function <> should be called by the FMU with further information before returning this status, respecting the current logging settings. If a function returns <>, it is possible to restore a previously retrieved FMU state by calling <> or to reset the instance by calling <>. -When detecting illegal arguments or a function call not allowed in the current state according to the respective state machine, the FMU must return <>. +When detecting illegal arguments or a function call not allowed in the current state machine mode according to the respective state machine, the FMU must return <>. Other instances of this FMU are not affected by the error. + -_[For example, when setting a constant with a call to <>, then the function must return with an error (<>.]_ +_[For example, when setting a constant with a call to <>, then the function must return with an error <>.]_ [[fmi3Fatal,`fmi3Fatal`]] `fmi3Fatal`:: @@ -337,7 +337,7 @@ If an API function takes multiple value references, the serialized variables are ===== Getting and Setting Variable Values [[get-and-set-variable-values]] -Restrictions for setting and getting of variables with certain types, causalities and variabilities are defined in the state machine and state descriptions (see <> for common states, <> for Model Exchange, <> for Co-Simulation, and <> for Scheduled Execution). +Restrictions for setting and getting of variables with certain types, causalities and variabilities are defined in the state machine and state machine mode descriptions (see <> for common state machine modes, <> for Model Exchange, <> for Co-Simulation, and <> for Scheduled Execution). In addition to those state-specific restrictions, setting and getting of <> is only allowed during <> when their respective Clocks are active, and during <> irrespective of Clock activation status. The variable <> defined in the <> determines the function <> (see also <> and <>) that must be used for accessing the respective variable values. @@ -1125,15 +1125,15 @@ where ** <> (Co-Simulation): The variables listed as elements <> of <> with a floating point type and <> = <> or <>. Each continuous state derivative variable listed as elements <> in <>, if present. -* latexmath:[\mathbf{v}_{\mathit{known}}] is the vector of arguments of function latexmath:[\mathbf{f}] which can be changed by the importer in the current state. +* latexmath:[\mathbf{v}_{\mathit{known}}] is the vector of arguments of function latexmath:[\mathbf{f}] which can be changed by the importer in the current state machine mode. Details about which variables are in latexmath:[\mathbf{v}_{\mathit{known}}] are given in the description of element <> in <>. -* latexmath:[{\mathbf{v}_{\mathit{rest}}}] is the set of <> variables and discrete-time states of function latexmath:[\mathbf{f}] which cannot be set by the importer in the current state, but in other states _[for example, discrete-time <> in <>]_. +* latexmath:[{\mathbf{v}_{\mathit{rest}}}] is the set of <> variables and discrete-time states of function latexmath:[\mathbf{f}] which cannot be set by the importer in the current state machine mode, but in other state machine modes _[for example, discrete-time <> in <>]_. * <> must not be included among latexmath:[\mathbf{v}_{\mathit{unknown}}]. + _[This is intentional as their dependencies listed in <> are intended for debugging purposes and not for partial derivatives.]_ -_[The variable relationships are different in different states._ +_[The variable relationships are different in different state machine modes._ _For example, during <>, the partial derivate of a continuous-time output_ latexmath:[\mathbf{y}] _with respect to discrete-time <> is undefined, because discrete-time <> cannot be set between events.]_ There are two access functions for partial derivatives: @@ -1178,7 +1178,7 @@ Both functions have the same arguments: * `nUnknowns` contains the length of argument `unknowns`. * `knowns` contains value references of the knowns. * `nKnowns` contains the length of argument `knowns`. -* `seed` contains the <> components of the seed vector. +* `seed` contains the <> components of the seed vector. * `nSeed` contains the length of `seed`. * `sensitivity` contains the <> components of the sensitivity vector. * `nSensitivity` contains the length of `sensitivity`. diff --git a/docs/2_3_common_states.adoc b/docs/2_3_common_states.adoc index 2e0c53a1c..3fe68d7be 100644 --- a/docs/2_3_common_states.adoc +++ b/docs/2_3_common_states.adoc @@ -1,13 +1,13 @@ === State Machine and Semantics [[common-state-machine]] To define allowed calling sequences of FMI functions, state machines are used. -Each state of the state machine corresponds to a certain phase of a simulation. -All interface types share a number of states in their respective state machines. -This chapter describes these common states used in at least two of the interface types. -State-machine states specific to a single interface type will be described in their respective chapters. +Each state machine mode corresponds to a certain phase of a simulation. +All interface types share a number of state machine modes in their respective state machines. +This chapter describes these common state machine modes used in at least two of the interface types. +State machine modes specific to a single interface type will be described in their respective chapters. [[each-state-description]] -Each state description lists the governing equations and actions and the corresponding API functions influencing these equations in a table (not defining the calling order), and also lists the allowed function calls and usage restrictions. +Each state machine mode description lists the governing equations and actions and the corresponding API functions influencing these equations in a table (not defining the calling order), and also lists the allowed function calls and usage restrictions. .Common calling sequence for C functions of common states for at least two of the interface types. [#figure-common-state-machine] @@ -15,13 +15,13 @@ image::images/state-machines-common-states.svg[width=80%, align="center"] The state machine is given here as UML 2.0 state machine. If a transition is labeled with one or more function names (for example, <>, <>), the transition is taken if the function call returns successfully (not `NULL` for <> or <> and <> for all other functions). -This way, importer and FMU can determine in which state the FMU is. +This way, importer and FMU can determine in which state machine mode the FMU is. ==== Super State: FMU State Settable [[FMUStateSettable,*FMU State Settable*]] -The state <> is entered when any of the following functions is called: <>, <> and <>. -The state is left by either calling <> or when any of the functions called during <> returns <>. -If any function called in super state <> returns <>, the FMU enters state <>. +The state machine mode <> is entered when any of the following functions is called: <>, <> and <>. +The state machine mode is left by either calling <> or when any of the functions called during <> returns <>. +If any function called in super state <> returns <>, the FMU enters state machine mode <>. Allowed Function Calls to enter this Super State:: @@ -179,7 +179,7 @@ include::../headers/fmi3FunctionTypes.h[tags=Reset] ---- + Is called by the environment to reset the FMU after a simulation run. -The FMU goes into the same state as if <> would have been called. +The FMU goes into the same state machine mode as if <> would have been called. All variables have their default values. Before starting a new run <> has to be called. @@ -204,7 +204,7 @@ All these allowed functions are described in <>. ==== State: Instantiated [[Instantiated,*Instantiated*]] -In the state <> the FMU can do one-time initializations and allocate memory. +In the state machine mode <> the FMU can do one-time initializations and allocate memory. [#table-math-instantiated] [cols="2,1",options="header"] @@ -288,7 +288,7 @@ Function `fmi3EnterInitializationMode`:: include::../headers/fmi3FunctionTypes.h[tags=EnterInitializationMode] ---- + -Changes state to <>. +Changes state machine mode to <>. * [[toleranceDefined,`toleranceDefined`]]`toleranceDefined` and * [[tolerance,`tolerance`]]`tolerance` depend on the interface type: @@ -429,7 +429,7 @@ include::../headers/fmi3FunctionTypes.h[tags=ExitInitializationMode] ---- + -Changes the state to +Changes the state machine mode to * Model Exchange: <> * Co-Simulation: diff --git a/docs/2_4_common_schema.adoc b/docs/2_4_common_schema.adoc index 1bd6a871a..964de0446 100644 --- a/docs/2_4_common_schema.adoc +++ b/docs/2_4_common_schema.adoc @@ -813,10 +813,10 @@ A tool may ignore this information. + _[However, it is convenient for a user that <>, <>, <> and <> have already a meaningful default value for the model at hand.]_ + <>, <> and <> refer to the unit of the <> variable. <> defines the preferred <> for Co-Simulation. -For Model Exchange and Scheduled Execution <> has no defined meaning. +For Model Exchange and Scheduled Execution <> has no defined meaning. _[This does not prohibit the use of <> in the context of Model Exchange._ _For example, a fixed step size solver can use it as a default step size._ -_A variable step size solver can use the <> as an initial step size or as result grid for the output._ +_A variable step size solver can use the <> as an initial step size or as result grid for the output._ _Since the required <> depends on the solver itself a defined meaning of <> for Model Exchange is impossible.]_ [[ModelVariables,``]] @@ -1950,7 +1950,7 @@ An importer should connect terminals only if the number of member variables matc [[none,`none`]] |`none` -|Matching of the variables is not intended by the creator of the FMU. +|Matching of the variables is not intended by the creator of the FMU. However, an importer may still connect terminals based on additional information. |==== @@ -1968,7 +1968,7 @@ This allows the same variable to participate in different connection contexts or [[terminalKind,`terminalKind`]] The normalized string `terminalKind` is an optional attribute. -Other standards may define terminal kinds. +Other standards may define terminal kinds. It is strongly recommended to use <> to define a `terminalKind`. It is intended that the `terminalKind` is used to define domain specific member variable sequences, member names and order, or high level restrictions for connections. diff --git a/docs/2_5_fmu_distribution.adoc b/docs/2_5_fmu_distribution.adoc index a1a41fac7..129cda7ac 100644 --- a/docs/2_5_fmu_distribution.adoc +++ b/docs/2_5_fmu_distribution.adoc @@ -51,7 +51,7 @@ sources // directory containing the C sources (optio binaries // directory containing the binaries (optional) x86_64-windows // binaries for Windows on Intel 64-bit .dll // shared library of the FMI implementation - // other platform dependend files + // other platform dependend files // needed at linking or loading time x86-linux // binaries for Linux on Intel 32-bit .so // shared library of the FMI implementation @@ -209,7 +209,7 @@ For the FMU to access these resource files - during runtime, after instantiation The resources directory must be available for the lifetime of the FMU instance. The FMU instance must not write to or delete the directory or parts of it. -_[The files contained in the resources folder may be platform dependent files. +_[The files contained in the resources folder may be platform dependent files. In contrast to files in the binaries folder, they can be accessed during runtime by the FMU. For more information, please consult the https://modelica.github.io/fmi-guides/main/fmi-guide/[FMI Implementer's Guide].]_ diff --git a/docs/3_2_model_exchange_api.adoc b/docs/3_2_model_exchange_api.adoc index 980a4496a..c066c6c16 100644 --- a/docs/3_2_model_exchange_api.adoc +++ b/docs/3_2_model_exchange_api.adoc @@ -6,14 +6,14 @@ The state machine in <> defines the allowed [#figure-model-exchange-state-machine] image::images/state-machine-model-exchange.svg[width=80%, align="center"] -Common states are defined in <>, such as super states <> and <>, states <>, <>, <>, <>, <> and <>. +Common state machine modes are defined in <>, such as super modes <> and <>, modes <>, <>, <>, <>, <> and <>. ==== State: Continuous-Time Mode [[ContinuousTimeMode,*Continuous-Time Mode*]] The <> is used to compute the values of all continuous-time variables between events by numerically solving ordinary differential and <>. All discrete-time variables are fixed during this phase and the corresponding discrete-time equations are not evaluated. -In this state, the continuous-time equations are active and integrator steps are performed by the importer. +In this mode, the continuous-time equations are active and integrator steps are performed by the importer. [#table-math-model-exchange] [cols="8,3",options="header"] @@ -185,7 +185,7 @@ Function `fmi3EnterEventMode`:: include::../headers/fmi3FunctionTypes.h[tags=EnterEventMode] ---- + -This function changes the state to <>. +This function changes the state machine mode to <>. + The importer must call <> when any of the following conditions are met: diff --git a/docs/4_2_co-simulation_api.adoc b/docs/4_2_co-simulation_api.adoc index 6e4fae6e9..5b89a52b6 100644 --- a/docs/4_2_co-simulation_api.adoc +++ b/docs/4_2_co-simulation_api.adoc @@ -6,11 +6,11 @@ The state machine in <> defines the allowed [#figure-co-simulation-state-machine] image::images/state-machine-co-simulation.svg[width=80%, align="center"] -Common states are defined in <>, such as super states <> and <>, states <>, <>, <>, <>, <>, and <>. +Common state machine modes are defined in <>, such as super modes <> and <>, modes <>, <>, <>, <>, <>, and <>. ==== State: Step Mode [[StepMode,*Step Mode*]] -The state <> is used to compute the values of all variables between communication points and events and to advance time in the FMU. +The state machine mode <> is used to compute the values of all variables between communication points and events and to advance time in the FMU. If the FMU is connected in <> with other models, iterations over the FMU equations requires <> (using <> and <>) and repeating <>. During <>, <> can not be set or get because <> are only active during <>. @@ -115,7 +115,7 @@ Reasons for <> are ** expressed by the return arguments <> or <> of <>, or ** the FMU's reaction to the importers request for <> by the return argument <> of <>, or ** the FMU's request for a communication point at <> for any other reason. -+ ++ <> must not be used to signal that the requested step was not completed due to an error _[(e.g. integrator encountered division by zero)]_. Instead, the function must return with an error code (<> or <>). Alternatively, the function can return with <>, if the FMU is in the same state as before the call, i.e. the output argument values are undefined, but the computation may continue. @@ -139,7 +139,7 @@ Function <>:: include::../headers/fmi3FunctionTypes.h[tags=EnterEventMode] ---- + -This function changes the state to <>. +This function changes the state machine mode to <>. + The importer must call <> when any of the following conditions are met: + @@ -190,7 +190,7 @@ It distinguishes the level of trust that can be placed in the tentative outputs [#figure-IntermediateUpdateMode] image::images/intermediateupdate.svg[width=65%, align="center"] -The FMU enters <> by calling <> within <> and leaves the state towards <> when the function returns. +The FMU enters <> by calling <> within <> and leaves the state machine mode towards <> when the function returns. [[fmi3IntermediateUpdateCallback,`fmi3IntermediateUpdateCallback`]] [source, C] diff --git a/docs/5_2_scheduled_execution_api.adoc b/docs/5_2_scheduled_execution_api.adoc index 2c07c2032..5d7e17d1f 100644 --- a/docs/5_2_scheduled_execution_api.adoc +++ b/docs/5_2_scheduled_execution_api.adoc @@ -6,15 +6,15 @@ The state machine in <> defines the al [#figure-scheduled-execution-state-machine] image::images/state-machine-scheduled-execution.svg[width=80%, align="center"] -Common states are defined in <>, such as super states <> and <>, states <>, <>, <>, <>, and <>. +Common state machine modes are defined in <>, such as super modes <> and <>, modes <>, <>, <>, <>, and <>. State changes are global to all model partitions, except to and from <>. -E.g. if any function call returns <> or <>, all active or preempted model partitions are in the same state. +E.g. if any function call returns <> or <>, all active or preempted model partitions are in the same state machine mode. In Scheduled Execution, <> must be treated like <>. -If the simulation algorithm intends to enter the state <>, it must ensure that all function calls related to model partitions of the FMU have returned. -If in states <>, <>, or <> a function returns <>, the importer may prematurely end all computations of model partitions of this FMU. -If in these states a function returns <> or <> the importer may wait until all other model partitions of this FMU have ended, but new model partitions must not be started and all other function calls for this FMU must return <> until the state <> is reached. +If the simulation algorithm intends to enter the state machine mode <>, it must ensure that all function calls related to model partitions of the FMU have returned. +If in state machine modes <>, <>, or <> a function returns <>, the importer may prematurely end all computations of model partitions of this FMU. +If in these state machine modes a function returns <> or <> the importer may wait until all other model partitions of this FMU have ended, but new model partitions must not be started and all other function calls for this FMU must return <> until the state machine mode <> is reached. ==== State: Clock Activation Mode [[ClockActivationMode,*Clock Activation Mode*]] diff --git a/docs/7___appendix.adoc b/docs/7___appendix.adoc index bcbde7873..785df8c64 100644 --- a/docs/7___appendix.adoc +++ b/docs/7___appendix.adoc @@ -179,7 +179,7 @@ Examples are a mass, stiffness, etc. These parameters are different from <>, because they can be changed independently (according to their <>). |[[reverse-DNS]]_reverse domain name notation_ -|A naming convention based on registered domain names, with the order of the components reversed for grouping purposes. +|A naming convention based on registered domain names, with the order of the components reversed for grouping purposes. |[[reinitialization]]_reinitialization_ |Recalculation of <> by the model.