From 3510d0d45d0321b618afcdce0cd1290607235064 Mon Sep 17 00:00:00 2001
From: Maplesoft FMI <fmigroup@maplesoft.com>
Date: Wed, 14 Dec 2022 15:40:31 -0500
Subject: [PATCH 1/3] Clarify earlyReturn from fmi3DoStep

Added a comment that this should not be used if the step terminated early due to an error to resolve #1844
---
 docs/4_2_co-simulation_api.adoc | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)

diff --git a/docs/4_2_co-simulation_api.adoc b/docs/4_2_co-simulation_api.adoc
index 9caefe390..7f429f599 100644
--- a/docs/4_2_co-simulation_api.adoc
+++ b/docs/4_2_co-simulation_api.adoc
@@ -103,7 +103,7 @@ _Both arguments <<currentCommunicationPoint>> and <<communicationStepSize>> allo
 _[The FMU can use this flag to flush a result buffer.]_
 
 * [[eventHandlingNeeded,`eventHandlingNeeded`]] <<eventHandlingNeeded,`eventHandlingNeeded = fmi3True`>> indicates that an event was encountered by the FMU at <<lastSuccessfulTime>> and the importer has to enter <<EventMode>> by calling <<fmi3EnterEventModeCS>>.
-<<eventHandlingNeeded,`eventHandlingNeeded = fmi3True`>> must not be signaled, if the importer indicates to not support <<EventMode>> by <<eventModeUsed,`eventModeUsed = fmi3False`>>.
+<<eventHandlingNeeded,`eventHandlingNeeded = fmi3True`>> must not be signalled, if the importer indicates to not support <<EventMode>> by <<eventModeUsed,`eventModeUsed = fmi3False`>>.
 _[This is different from <<earlyReturn>> which only indicates that the <<fmi3DoStep>> did not complete the intended step up until <<currentCommunicationPoint>> + <<communicationStepSize>> and does not require event handling.]_
 
 * [[terminateSimulationDS,`terminateSimulation`]] When <<terminateSimulationDS,`terminateSimulation = fmi3True`>>, the FMU requests to stop the simulation and the importer must call <<fmi3Terminate>>.
@@ -115,6 +115,8 @@ Reasons for <<earlyReturn, `earlyReturn = fmi3True`>> are
 ** expressed by the return arguments <<eventHandlingNeeded>> or <<terminateSimulationDS>> of <<fmi3DoStep>>, or
 ** the FMU's reaction to the importers request for <<earlyReturn>> by the return argument <<earlyReturnRequested, `earlyReturnRequested = fmi3True`>> of <<fmi3IntermediateUpdateCallback>>, or
 ** the FMU's request for a communication point at <<lastSuccessfulTime>> for any other reason.
++ 
+<<earlyReturn,`earlyReturn = fmi3True`>> must not be used to signal that the requested step was not completed due to an error (e.g. integrator encountered division by zero).
 
 * [[lastSuccessfulTime,`lastSuccessfulTime`]] `lastSuccessfulTime` represents the internal time latexmath:[t_{i+1}] of the FMU when <<fmi3DoStep>> returns, for any value of <<earlyReturn>>.
 It is possible that the <<lastSuccessfulTime>> is equal to <<currentCommunicationPoint>> when <<earlyReturn,`earlyReturn = fmi3True`>> to indicate, for example, the detection of an event at <<currentCommunicationPoint>>.

From a14532251010324a07fc4380ce5ad059ebea9b05 Mon Sep 17 00:00:00 2001
From: Andreas Junghanns <andreas.junghanns@gmx.net>
Date: Thu, 15 Dec 2022 08:09:15 +0100
Subject: [PATCH 2/3] Ultra-clarify

---
 docs/4_2_co-simulation_api.adoc | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/docs/4_2_co-simulation_api.adoc b/docs/4_2_co-simulation_api.adoc
index 7f429f599..2a8d61720 100644
--- a/docs/4_2_co-simulation_api.adoc
+++ b/docs/4_2_co-simulation_api.adoc
@@ -116,7 +116,8 @@ Reasons for <<earlyReturn, `earlyReturn = fmi3True`>> are
 ** the FMU's reaction to the importers request for <<earlyReturn>> by the return argument <<earlyReturnRequested, `earlyReturnRequested = fmi3True`>> of <<fmi3IntermediateUpdateCallback>>, or
 ** the FMU's request for a communication point at <<lastSuccessfulTime>> for any other reason.
 + 
-<<earlyReturn,`earlyReturn = fmi3True`>> must not be used to signal that the requested step was not completed due to an error (e.g. integrator encountered division by zero).
+<<earlyReturn,`earlyReturn = fmi3True`>> 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 (<<fmi3Error>> or <<fmi3Fatal>>).
 
 * [[lastSuccessfulTime,`lastSuccessfulTime`]] `lastSuccessfulTime` represents the internal time latexmath:[t_{i+1}] of the FMU when <<fmi3DoStep>> returns, for any value of <<earlyReturn>>.
 It is possible that the <<lastSuccessfulTime>> is equal to <<currentCommunicationPoint>> when <<earlyReturn,`earlyReturn = fmi3True`>> to indicate, for example, the detection of an event at <<currentCommunicationPoint>>.

From 18c4a9ec5925dc9016d3ca819a7f6bd586db1c3f Mon Sep 17 00:00:00 2001
From: Christian Bertsch <Christian.Bertsch@de.bosch.com>
Date: Tue, 10 Jan 2023 19:57:52 +0100
Subject: [PATCH 3/3] Update docs/4_2_co-simulation_api.adoc

Co-authored-by: Pierre R. Mai <pmai@pmsf.de>
---
 docs/4_2_co-simulation_api.adoc | 1 +
 1 file changed, 1 insertion(+)

diff --git a/docs/4_2_co-simulation_api.adoc b/docs/4_2_co-simulation_api.adoc
index 2a8d61720..9bf84aeb2 100644
--- a/docs/4_2_co-simulation_api.adoc
+++ b/docs/4_2_co-simulation_api.adoc
@@ -118,6 +118,7 @@ Reasons for <<earlyReturn, `earlyReturn = fmi3True`>> are
 + 
 <<earlyReturn,`earlyReturn = fmi3True`>> 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 (<<fmi3Error>> or <<fmi3Fatal>>).
+Alternatively, the function can return with <<fmi3Discard>>, 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.
 
 * [[lastSuccessfulTime,`lastSuccessfulTime`]] `lastSuccessfulTime` represents the internal time latexmath:[t_{i+1}] of the FMU when <<fmi3DoStep>> returns, for any value of <<earlyReturn>>.
 It is possible that the <<lastSuccessfulTime>> is equal to <<currentCommunicationPoint>> when <<earlyReturn,`earlyReturn = fmi3True`>> to indicate, for example, the detection of an event at <<currentCommunicationPoint>>.