Merge pull request #802 from kordejong/gh788

Refactor, add docs

source/framework/model/include/lue/framework/model/model.hpp

@@ -25,15 +25,15 @@ namespace lue {
 
             virtual ~Model() = default;
 
-            Model& operator=(Model const&) = default;
+            auto operator=(Model const&) -> Model& = default;
 
-            Model& operator=(Model&&) = default;
+            auto operator=(Model&&) -> Model& = default;
 
-            virtual void preprocess(Count const sample_nr);
+            virtual void preprocess(Count sample_nr);
 
             virtual void initialize();
 
-            virtual hpx::shared_future<void> simulate(Count const time_step);
+            virtual auto simulate(Count time_step) -> hpx::shared_future<void>;
 
             virtual void finalize();
 
@@ -43,11 +43,11 @@ namespace lue {
     };
 
 
-    void preprocess(Model& model, Count const sample_nr);
+    void preprocess(Model& model, Count sample_nr);
 
     void initialize(Model& model);
 
-    hpx::shared_future<void> simulate(Model& model, Count const time_step);
+    auto simulate(Model& model, Count time_step) -> hpx::shared_future<void>;
 
     void finalize(Model& model);
 

source/framework/model/include/lue/framework/model/simulate.hpp

@@ -48,7 +48,9 @@ namespace lue {
         lue_hpx_assert(first_time_step <= last_time_step);
 
         Count const nr_time_steps{last_time_step - first_time_step + 1};
-        rate_limit = rate_limit > 0 ? rate_limit : nr_time_steps;
+        bool const rate_limit_used{rate_limit > 0};
+        Count const default_rate_limit{nr_time_steps};
+        rate_limit = rate_limit_used ? rate_limit : default_rate_limit;
 
         std::int64_t const max_difference{rate_limit};
         std::int64_t const lower_limit{first_time_step};

source/framework/model/source/model.cpp

@@ -16,8 +16,8 @@ namespace lue {
     /*!
         @brief      Initialize the modelled state
 
-        The current state of the simulated system is undefined. After calling
-        this function, it must be representable for t = 0.
+        The current state of the simulated system is undefined. After calling this function, it must be
+        representable for t = 0.
 
         The default does nothing.
     */
@@ -27,16 +27,19 @@ namespace lue {
 
 
     /*!
-        @brief      Simulate the state of the modelled system during an
-                    additional time step (t = t + 1)
+        @brief      Simulate the state of the modelled system during an additional time step (t = t + 1)
+        @warning    The returned future must reflect the status of the work that has to be done to end up
+                    state of t + 1. The future must become ready only once this work has finished. Typically,
+                    the (partitions of the) last state variable can be used for that. Knowing when the work
+                    related to a time step has finished is crucial for being able to limit the rate with
+                    which tasks are created (see for example run_deterministic()).
 
-        The current state of the simulated system is representable for t =
-        t. After calling this function, it must be representable for t =
-        t + 1.
+        The current state of the simulated system is representable for t = t. After calling this function, it
+        must be representable for t = t + 1.
 
         The default does nothing.
     */
-    hpx::shared_future<void> Model::simulate([[maybe_unused]] Count const time_step)
+    auto Model::simulate([[maybe_unused]] Count const time_step) -> hpx::shared_future<void>
     {
         return hpx::make_ready_future<void>();
     }
@@ -85,7 +88,7 @@ namespace lue {
     /*!
         @brief      Call Model.simulate(Count const)
     */
-    hpx::shared_future<void> simulate(Model& model, Count const time_step)
+    auto simulate(Model& model, Count const time_step) -> hpx::shared_future<void>
     {
         return model.simulate(time_step);
     }

source/framework/python/source/model/model.cpp

@@ -28,7 +28,7 @@ namespace lue::framework {
             }
 
 
-            hpx::shared_future<void> simulate(Count const time_step) override
+            auto simulate(Count const time_step) -> hpx::shared_future<void> override
             {
                 PYBIND11_OVERRIDE(hpx::shared_future<void>, Model, simulate, time_step);
             }