Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Reformat and rename simulation engine functions #357

Merged
merged 20 commits into from
Dec 9, 2024
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
20 commits
Select commit Hold shift + click to select a range
50238b6
Remove redundant doc and directory
patkenneally Nov 8, 2024
061dc53
Rename UpdateState to updateState
patkenneally Nov 8, 2024
a86335e
Rename Reset to reset
patkenneally Nov 8, 2024
923dac1
Rename SelfInit and IntegratedInit to selfInit and integratedInit
patkenneally Nov 8, 2024
27bdd18
Rename ModelTag to modelTag
patkenneally Nov 8, 2024
cb5d2aa
Rename all CurrentSimNanos instances to currentSimNanos
patkenneally Nov 8, 2024
c33eed4
Rename variable so different to reset function name
patkenneally Nov 8, 2024
720aa2b
Rename SingleStepProcesses to singleStepProcesses
patkenneally Nov 19, 2024
504bf46
Rename disableAllTasks to disableTasks
patkenneally Nov 19, 2024
fed98db
Rename enableAllTasks to enableTasks
patkenneally Nov 19, 2024
e62905a
Rename StepUntilStop to stepUntilStop
patkenneally Nov 19, 2024
dbf75fc
Rename processEnabled to isEnabled
patkenneally Nov 19, 2024
eca7026
Rename addNewTask to addTask
patkenneally Nov 19, 2024
b7fcf39
Rename AddNewObject to addModel
patkenneally Nov 19, 2024
8ac0111
Rename thread StepUntilStop to stepUntilStop
patkenneally Nov 19, 2024
90ab77b
Rename thread SingleStepProcess to singleStepProcess
patkenneally Nov 19, 2024
dda9dcc
Remove redundant process word from sys_process function names
patkenneally Nov 19, 2024
5486ac0
Remove redundant task word from SysModelTask function names
patkenneally Nov 19, 2024
9a2fde4
Rename ResetSimulation to resetSimulation
patkenneally Nov 19, 2024
0ebd248
Clean up formatting
patkenneally Nov 19, 2024
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
The table of contents is too big for display.
Diff view
Diff view
  •  
  •  
  •  
14 changes: 7 additions & 7 deletions docs/source/Learn/bskPrinciples/bskPrinciples-10.rst
Original file line number Diff line number Diff line change
@@ -1,40 +1,40 @@
.. _bskPrinciples-10:

.. warning::
.. warning::

This section refers to a deprecated way of operating with C modules. Refer to previous documentation pages for the updated way.

Deprecated: Using old-style C modules
=====================================
In more recent Basilisk scripts, whether a module is implemented in C++ or C should not make
any difference on how this module is used in Python scripts. However, this has not always been
the case, and you might encounter some code that uses the older syntax. This documentation
the case, and you might encounter some code that uses the older syntax. This documentation
summarizes how to use this older syntax.

Previous documentation pages have taught us that C++ modules (and new-syntax C modules) are
created, configured, and added to the simulation through the following syntax::

module = someModule.someModule()
module.someParameter = 5
module.ModelTag = "someModuleName"
module.modelTag = "someModuleName"
scSim.AddModelToTask("taskName", module, priority)

In order to perform the same operations on an old-syntax C module, one would do::

moduleConfig = someModule.someModuleConfig()
moduleConfig.someParameter = 5
moduleWrap = scSim.setModelDataWrap(moduleConfig)
moduleWrap.ModelTag = "someModuleName"
moduleWrap.modelTag = "someModuleName"
scSim.AddModelToTask("taskName", moduleWrap, moduleConfig, priority)

Note that in this case, we created a "Config" object ``someModule.someModuleConfig``. Connecting
Note that in this case, we created a "Config" object ``someModule.someModuleConfig``. Connecting
messages and setting parameters of the module is done through this object. Then, the ``setModelDataWrap``
method of the simulation object is called on the "Config" object, which generates the "Wrap" object.
The unique name must be set on the "Wrap" object. Finally, the module is added to the simulation by
using both the "Wrap" and "Config" objects in the ``scSim.AddModelToTask`` method.

The need for separate "Config" and "Wrap" objects arises from the lack of classes in the C programming language.
The "Config" objects, as well as the relevant ``UpdateState``, ``Reset``, and ``SelfInit`` methods,
The need for separate "Config" and "Wrap" objects arises from the lack of classes in the C programming language.
The "Config" objects, as well as the relevant ``updateState``, ``Reset``, and ``SelfInit`` methods,
are written in pure C for C modules. However, the simulation framework is written in C++ and it expects
the modules to be C++ classes. The "Wrap" object is this C++ class, which holds references to
the "Config" object and the relevant methods so that they can be accesses from C++ as a single class.
Expand Down
4 changes: 2 additions & 2 deletions docs/source/Learn/bskPrinciples/bskPrinciples-11.rst
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@

.. _bskPrinciples-11:

.. warning::
.. warning::

This section refers to a deprecated way of logging variables. Refer to previous documentation pages for the updated way.

Expand All @@ -28,4 +28,4 @@ the :ref:`SimulationBaseClass` method::

scSim.GetLogVariableData(variableString)

Here ``variableString`` is again composed of the ``ModelTag`` and variable name as before. Note that the returned array has a first column that represents the time where the variable is recorded in nano-seconds. Executing the script you should thus see the following output:
Here ``variableString`` is again composed of the ``modelTag`` and variable name as before. Note that the returned array has a first column that represents the time where the variable is recorded in nano-seconds. Executing the script you should thus see the following output:
4 changes: 2 additions & 2 deletions docs/source/Learn/bskPrinciples/bskPrinciples-2.rst
Original file line number Diff line number Diff line change
Expand Up @@ -28,7 +28,7 @@ The following simulation creates a single process called ``dynamicsProcess`` and
The resulting demonstration code is shown above. Let us create some module ``someModule.someModule`` and give it a unique name. This is done as::

module = someModule.someModule()
module.ModelTag = "someModuleName"
module.modelTag = "someModuleName"

With BSK C-modules the module name is repeated. With C++ modules the first variable is the module name, the second
variable is the module class name which begins with a capital letter. See the above script for examples of each.
Expand Down Expand Up @@ -73,6 +73,6 @@ If you execute this python code you should see the following terminal output:
BSK_INFORMATION: C Module ID 1 ran Update at 5.000000s
:ref:`cModuleTemplate` and :ref:`cppModuleTemplate` log in the ``Reset()`` method that a variable has been set to 0. As we have three such modules, notice that this reset statement is seen three times. This reset step occurs when we run ``scSim.InitializeSimulation()``.
:ref:`cModuleTemplate` and :ref:`cppModuleTemplate` log in the ``reset()`` method that a variable has been set to 0. As we have three such modules, notice that this reset statement is seen three times. This reset step occurs when we run ``scSim.InitializeSimulation()``.

After the initialization, Basilisk starts the time loop evaluating the modules at the specified rate. The ``Update()`` routine in both :ref:`cModuleTemplate` and :ref:`cppModuleTemplate` print out the module ID and the simulation time where the module is called. Note that thanks to the module evaluation priorities we set, the desired module execution order is achieved.
12 changes: 5 additions & 7 deletions docs/source/Learn/bskPrinciples/bskPrinciples-2a.rst
Original file line number Diff line number Diff line change
Expand Up @@ -10,18 +10,18 @@ Execution of Basilisk Modules

This guide discusses the main functions that a Basilisk module must perform during setup and when running the simulation. Each Basilisk module has 3 key methods that it must be able to perform:

``SelfInit()``: With the C-modules this method acts as the constructor that connects the output messages to write to their own payload (i.e. message data). This step is not required with C++ modules.
``selfInit()``: With the C-modules this method acts as the constructor that connects the output messages to write to their own payload (i.e. message data). This step is not required with C++ modules.

``Reset()``: This method should reset the module variables to desired default states. For example, this is where the integral feedback gain might be reset to 0, where module parameters like the spacecraft, reaction wheel or thruster configuration messages are read it, etc. This method typically also does some sanity checks that the module is configured properly, and that required input messages are connected, etc.
``reset()``: This method should reset the module variables to desired default states. For example, this is where the integral feedback gain might be reset to 0, where module parameters like the spacecraft, reaction wheel or thruster configuration messages are read it, etc. This method typically also does some sanity checks that the module is configured properly, and that required input messages are connected, etc.

``Update()``: This is the primary module routine that is called every time the simulation advanced one time step. This routine shoudl controll all the functions that this module is to perform.

The function ``scSim.InitializeSimulation()`` calls ``SelfInit()`` and ``Reset()`` for each module. The ``Update()`` mehtod is called each task time step when the simulation is executed.
The function ``scSim.InitializeSimulation()`` calls ``selfInit()`` and ``reset()`` for each module. The ``Update()`` mehtod is called each task time step when the simulation is executed.

.. image:: ../../_images/static/qs-bsk-2a.svg
:align: center

The sample script below creates a single Basilisk module as illustrated above. The module variable ``dummy`` is set to a non-zero value after the module is created. The ``InitializeSimulation()`` method calls ``Reset()`` which sets this ``dummy`` variable equal to zero.
The sample script below creates a single Basilisk module as illustrated above. The module variable ``dummy`` is set to a non-zero value after the module is created. The ``InitializeSimulation()`` method calls ``reset()`` which sets this ``dummy`` variable equal to zero.

.. literalinclude:: ../../codeSamples/bsk-2a.py
:language: python
Expand All @@ -30,7 +30,7 @@ The sample script below creates a single Basilisk module as illustrated above.

To execute the code, this script doesn't run the simulation for a period of time. Rather, the simulation is executed for a single time step. This is convenient in particular when testing the module input-output behavior. The command to execute Basilisk for one time step is::

scSim.TotalSim.SingleStepProcesses()
scSim.TotalSim.singleStepProcesses()

After the single process step execution the module ``dummy`` variable is printed out again to illustrate that an ``Update()`` call has occured. Looking at the module source code you see that this variable is zero'd on reset and incremented by +1 on each ``Update()`` call.

Expand All @@ -44,5 +44,3 @@ If you execute this python code you should see the following terminal output:
0.0
BSK_INFORMATION: C Module ID 1 ran Update at 0.000000s
1.0
4 changes: 1 addition & 3 deletions docs/source/Learn/bskPrinciples/bskPrinciples-8.rst
Original file line number Diff line number Diff line change
Expand Up @@ -23,7 +23,7 @@ The sample script below sets up a single process which contains 2 tasks called `

After performing the typical module initialization the script executes a single simulation step. The terminal output below shows that both the C and C++ modules have been executed, meaning both ``cTask`` and ``cppTask`` are enabled.

To disable all tasks within a process, the command ``disableAllTasks()`` can be called on the process variable. A single simulation step is executed with print statements before and after to illustrate not no tasks are being executed, as expected.
To disable all tasks within a process, the command ``disableTasks()`` can be called on the process variable. A single simulation step is executed with print statements before and after to illustrate not no tasks are being executed, as expected.

Next, the :ref:`SimulationBaseClass` command ``enableTask(name)`` is used to turn on the ``cTask``. The string argument is the name of the task being enabled. After executing another simulation step the terminal output illustrates that the C module is again executed. This is repeated for enabling ``cppTask``.

Expand All @@ -45,5 +45,3 @@ To disable a single task, this is done with the :ref:`SimulationBaseClass` metho
BSK executed a single simulation step
BSK_INFORMATION: C Module ID 1 ran Update at 4.000000s
BSK executed a single simulation step
8 changes: 4 additions & 4 deletions docs/source/Learn/bskPrinciples/bskPrinciples-9.rst
Original file line number Diff line number Diff line change
Expand Up @@ -3,8 +3,8 @@
Advanced: Using ``DynamicObject`` Basilisk Modules
==================================================
Basilisk modules such as :ref:`spacecraft` and :ref:`spacecraftSystem` are members of
the ``DynamicObject`` class. This means they still have the regular Basilisk ``Reset()`` and
``UpdateState()`` methods, but they also have a state machine and integrator build in as these
the ``DynamicObject`` class. This means they still have the regular Basilisk ``reset()`` and
``updateState()`` methods, but they also have a state machine and integrator build in as these
modules have to integrate internal ordinate differential equations (ODEs).

The ``DynamicObject`` class has the ability to integrate not just the ODEs of the one Basilisk module,
Expand All @@ -19,7 +19,7 @@ This steps ties the integration of ``scObject2`` to the integration of ``scObjec
``scObject`` is setup in a Basilisk task running 10Hz using the RK4 integrator, and ``scObject2`` is
in a 1Hz task and specifies an RK2 integrator, the ODE integration of the primary object overrides
the setup of the sync'd ``DynamicObjects``. As a result both objects would be integrated using
the RK4 integrator at 10Hz. The ``UpdateState()`` method of ``scObjects2`` would still be called
the RK4 integrator at 10Hz. The ``updateState()`` method of ``scObjects2`` would still be called
at 1Hz as this method is called at the task update period.

.. note::
Expand All @@ -32,4 +32,4 @@ at 1Hz as this method is called at the task update period.
The integration type is determined by the integrator assigned to the primary ``DynamicObject`` to
which the other ``DynamicObject`` integrations is synchronized. By default this is the ``RK4``
integrator. It doesn't matter what integrator is assigned to the secondary ``DynamicObject`` instances,
the integrator of the primary object is used.
the integrator of the primary object is used.
Original file line number Diff line number Diff line change
Expand Up @@ -4,12 +4,12 @@ Creating ``DynamicObject`` Basilisk Modules
===========================================

Basilisk modules that inherit from the class :ref:`dynamicObject` are still regular Basilisk modules
that have the typical ``SelfInit()``, ``Reset()`` and ``UpdateState()`` methods. However, they also contain
that have the typical ``selfInit()``, ``reset()`` and ``updateState()`` methods. However, they also contain
a state engine called ``dynManager`` of the class ``DynParamManager``, as well as an integrator
pointer called ``integrator`` of class ``StateVecIntegrator``. :ref:`spacecraft` is an example of
a Basilisk module that is also inheriting from the ``DynamicObject`` class.

In the spacecraft ``UpdateState()`` method the ``DynamicObject::integrateState()`` method is called.
In the spacecraft ``updateState()`` method the ``DynamicObject::integrateState()`` method is called.
This call integrates all the registered spacecraft states, as well as all the connect state
and dynamic effectors, to the next time step using the connected integrator type. See
:ref:`scenarioIntegrators` for an example how how to set the integrator on a dynamic object.
Expand All @@ -35,4 +35,3 @@ scenarios as with the spacecraft example. See the discussion in :ref:`bskPrinci
Basilisk modules that inherit from the ``DynamicObject`` class can be linked. If linked,
then the associated module ordinate differential equations (ODEs) are integrated
simultaneously.

3 changes: 1 addition & 2 deletions docs/source/Learn/makingModules/cModules/cModules-1.rst
Original file line number Diff line number Diff line change
Expand Up @@ -7,7 +7,7 @@ Basic C Module Setup
--------------------
This page describes how to create the C module functions. Because C is not an object oriented language it is necessary to recreate some concepts from C++ such as data encapsulation. Thus, while a C++ module has its variables defined within the class, with a C module we need to create a module configuration structure which contains all the module variables. The module config structure name should be the module name ending with ``....Config``.

When a C module is setup in python, the module data is created first by making an instance of the module configuration data structure, and then wrapping this with module specific code to make a functioning Basilisk module. The module wrapped is a sub-class of :ref:`sys_model` and thus has the usual ``ModelTag`` and ``moduleID`` variables, as well as the ability to respond to ``Reset()`` and ``UpdateState()`` requests.
When a C module is setup in python, the module data is created first by making an instance of the module configuration data structure, and then wrapping this with module specific code to make a functioning Basilisk module. The module wrapped is a sub-class of :ref:`sys_model` and thus has the usual ``modelTag`` and ``moduleID`` variables, as well as the ability to respond to ``reset()`` and ``updateState()`` requests.


Sample Code
Expand Down Expand Up @@ -83,4 +83,3 @@ For example, assume the module needs an array of input messages of type ``SomeMs
The module needs to implement separate logic to determine how many messages have been set. For example, the reset function could loop over this array and up to what slot the associate message object has been linked.

As the C wrapped message object can act as either input or output messages, the above example can readily be converted to an outpout message example by renaming the array variable ``moreOutMsgs``.

7 changes: 3 additions & 4 deletions docs/source/Learn/makingModules/cModules/cModules-3.rst
Original file line number Diff line number Diff line change
Expand Up @@ -31,10 +31,10 @@ Reset Method
The ``Reset_....()`` method should be used to

- restore module variables if needed. For example, the integral feedback gain variable might be reset to 0.
- perform one-time message reads such as reading in the reaction wheel or spacecraft configuration message etc. Whenever ``Reset()`` is called the module should read in these messages again to use the latest values.
- check that required input messages are connected. If a required input message is not connected when ``Reset()`` is called, then log a BSK error message.
- perform one-time message reads such as reading in the reaction wheel or spacecraft configuration message etc. Whenever ``reset()`` is called the module should read in these messages again to use the latest values.
- check that required input messages are connected. If a required input message is not connected when ``reset()`` is called, then log a BSK error message.

The following sample code assumes that the class variable ``value`` should be re-set to 0 on ``Reset()``, and that ``someInMsg`` is a required input message:L
The following sample code assumes that the class variable ``value`` should be re-set to 0 on ``reset()``, and that ``someInMsg`` is a required input message:L

.. code:: cpp
Expand Down Expand Up @@ -101,4 +101,3 @@ Assume the module has an array called ``moreInMsgs`` which contain input message
.. code:: cpp
inMsgBuffer = SomeMsg_C_read(&configData->moreInMsgs[3]);
9 changes: 4 additions & 5 deletions docs/source/Learn/makingModules/cppModules/cppModules-1.rst
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,7 @@ Module Header File

Parent Class
------------
Every Basilisk module is a sub-class of :ref:`sys_model`. This parent class provides common modules variables such as ``ModelTag`` and ``moduleID``.
Every Basilisk module is a sub-class of :ref:`sys_model`. This parent class provides common modules variables such as ``modelTag`` and ``moduleID``.

Module Class Name
-----------------
Expand All @@ -32,8 +32,8 @@ Let us assume the module is to be called ``SomeModule``. The input and output m
SomeModule();
~SomeModule();
void Reset(uint64_t CurrentSimNanos);
void UpdateState(uint64_t CurrentSimNanos);
void reset(uint64_t currentSimNanos);
void updateState(uint64_t currentSimNanos);
public:
Expand Down Expand Up @@ -69,7 +69,7 @@ Be sure to add descriptions to both the module and to the class variables used.

Required Module Methods
-----------------------
Each module should define the ``Reset()`` method that is called when initializing the BSK simulation, and the ``UpdateState()`` method which is called every time the task to which the module is added is updated.
Each module should define the ``reset()`` method that is called when initializing the BSK simulation, and the ``updateState()`` method which is called every time the task to which the module is added is updated.

Module Variables
----------------
Expand Down Expand Up @@ -105,4 +105,3 @@ To define a vector of output messages, we define a vector of message pointer usi
public:
std::vector<Message<SomeMsgPayload>*> moreOutMsgs; //!< variable description
Loading
Loading