Module: fswModuleTemplate¶

Executive Summary¶

Provide a brief introduction to purpose and intent of this module. This should be a short description. If this requires lots explanation, images, equations, etc., then used the Detailed Module Description section below.

Message Connection Descriptions¶

The following table lists all the module input and output messages. The module msg variable name is set by the user from python. The msg type contains a link to the message structure definition, while the description provides information on what this message is used for.

Module I/O Messages¶
Msg Variable Name	Msg Type	Description
dataInMsgName	Module: fswModuleTemplateFswMsg	Input message description. Note here if this message is optional, and what the default behavior is if this message is not provided.
dataOutMsgName	Module: fswModuleTemplateFswMsg	Output message description.

Detailed Module Description¶

Provide a brief introduction to the material being discussed in this report. For example, include what the motivation is, maybe provide a supportive figure such as shown below, reference earlier work if needed in a literature review web links. Describe the module including mathematics, implementation, etc.

Equations¶

Equations can be provided with LaTeX as well. For example, the code:

:math:`a = b^{2}`

produces this equation inline \(a = b^{2}\) equation. In contrast, this code:

.. math::
    a = b^2

or this compact version for 1 liners:

.. math:: a = b^2

creates this block of math.

\[a = b^2\]

To create a numbered equation you need to add a label:

.. math::
    :label: eq-firstLaw

    a = b^2

which creates this

(1)¶\[a = b^2\]

This label can be referenced using :eq:`eq-firstLaw` to cite Eq. (1).

To do bold math, we can’t use the popular \bm command. Instead, we can use {\bf u} (regular letters) or \pmb \omega (greek letters). The following math is an example of this showing both bold and un-bold letters next to each other:

(2)¶\[{\bf u} u = 3 \hat{\bf e}_3\]

(3)¶\[\pmb \omega \omega = 2 \hat{\imath}_{\theta}\]

More details on how to typeset TeX math in Sphinx can be found here.

If the module description requires extensive math discussion, this can be TeX’d up using the technical note template inside the _Documentation folder. A link should be included in the HTML documentation to the Detailed PDF Documentation using the code:

:download:`Detailed PDF Documentation </../../src/fswAlgorithms/_fswTemplateFolder/fswModuleTemplate/_Documentation/Basilisk-MODULENAME.pdf>`

The PDF technical should only be used as a last resort effort if the math is simply too complex and long to include in the spinx documentation. Another option is to link to a web site, conference paper, journal paper, book or thesis document that discussed the mathematical developments used.

Citations¶

If you want to cite other papers or text, provide a web link to a paper. For example:

`The link text <http://example.net/>`__

creates The link text.

Images and Figures¶

To include static, non-pytest generated images and figures, you must copy the web compatible image (svg, jpg, png) to a local sub-folder fswModuleTemplate/_Documentation/Images/. This keeps the modules images grouped within this sub-folder and contained within the main module folder. The SVG image format is preferred as it is a vectorized format that renders in a higher quality. Further, when viewed in dark mode the svg will automatically convert to a dark image (preserving colors). Pixelated formats such as jpg and png remain the same in light and dark mode of the documentation web page.

For example, to include an image (has no caption) you can use code such as:

.. image:: /../../src/fswAlgorithms/_fswTemplateFolder/fswModuleTemplate/_Documentation/Images/Fig1.svg
    :align: center

to generate the following image.

Note that with pixelated images such as jpg and png format save the file at twice the resolution that you need, then provide :scale: 50 % to shrink it to the normal size. This way the image has enough resolution to look good on high-resolution displays.

To include a figure (has a caption and you can add label), use the following code:

.. _figLabel:
.. figure:: /../../src/fswAlgorithms/_fswTemplateFolder/fswModuleTemplate/_Documentation/Images/Fig1.svg
    :align: center

    Figure 1: Concept Illustration of the Math used in this Module

This yields

Figure 1: Concept Illustration of the Math used in this Module¶

You can cite the figure using :ref:`figLabel`. For example, as seen in Figure 1: Concept Illustration of the Math used in this Module, the figure can now be referenced.

More information on how to include images or figures using sphinx can be found here. In particular, it is also possible to include an image as a figure which has a caption.

Tables¶

The standard sphinx table formatting can be used to generate tables. More information on spinx table formatting can be found here. For example, the code:

.. table:: Module I/O Messages

    +------------------------+------------+----------+----------+
    | Header row, column 1   | Header 2   | Header 3 | Header 4 |
    | (header rows optional) |            |          |          |
    +========================+============+==========+==========+
    | body row 1, column 1   | column 2   | column 3 | column 4 |
    +------------------------+------------+----------+----------+
    | body row 2             | Cells may span columns.          |
    +------------------------+------------+---------------------+
    | body row 3             | Cells may  | - Table cells       |
    +------------------------+ span rows. | - contain           |
    | body row 4             |            | - body elements.    |
    +------------------------+------------+---------------------+

will generate the following table:

Module I/O Messages¶
Header row, column 1 (header rows optional)	Header 2	Header 3	Header 4
body row 1, column 1	column 2	column 3	column 4
body row 2	Cells may span columns.
body row 3	Cells may span rows.	Table cells contain body elements.
body row 4	Cells may span rows.	Table cells contain body elements.

Note

Doing tables with spinx is not simple. The table outline must abide by tedious spacing rules.

HTML Highlight Options¶

With Sphinx you can easily create HTML highlight blocks called admonitions such as attention, caution, danger, error, hint, important, note, tip, warning. Here are samples of what these blocks look like.

Danger

text goes here

Error

text goes here

Attention

text goes here

Caution

text goes here

Warning

text goes here

Hint

text goes here

Important

text goes here

Tip

text goes here

Note

text goes here

Module Assumptions and Limitations¶

This section should describe the assumptions used in formulating the mathematical model and how those assumptions limit the usefulness of the module.

User Guide¶

This section contains information directed specifically to users. It contains clear descriptions of what inputs are needed and what effect they have. It should also help the user be able to use the model for the first time.

Add sample code as needed. For example, to specify that the module variables dummy and dumVector must be setup first, you can include python formatted code block using:

.. code-block:: python
    :linenos:

    moduleConfig.dummy = 1
    moduleConfig.dumVector = [1., 2., 3.]

to show:

moduleConfig.dummy = 1
moduleConfig.dumVector = [1., 2., 3.]

More information of including code blocks can be found here.

In the user guide, provide sub-sections as need to help explain how to use this module, list what variables must be set, discuss variables that might have default values if not specified by the user, etc.

Functions

void SelfInit_fswModuleTemplate(fswModuleTemplateConfig *configData, int64_t moduleID)¶

This method initializes the configData for this module. It checks to ensure that the inputs are sane and then creates the output message

Return

void

Parameters

configData: The configuration data associated with this module

void CrossInit_fswModuleTemplate(fswModuleTemplateConfig *configData, int64_t moduleID)¶

This method performs the second stage of initialization for this module. It’s primary function is to link the input messages that were created elsewhere. Nothing else should be happening in this function.

Return

void

Parameters

configData: The configuration data associated with this module

void Update_fswModuleTemplate(fswModuleTemplateConfig *configData, uint64_t callTime, int64_t moduleID)¶

Add a description of what this main Update() routine does for this module

Return

void

Parameters

configData: The configuration data associated with the module
callTime: The clock time at which the function was called (nanoseconds)

void Reset_fswModuleTemplate(fswModuleTemplateConfig *configData, uint64_t callTime, int64_t moduleID)¶

This method performs a complete reset of the module. Local module variables that retain time varying states between function calls are reset to their default values. The local copy of the message output buffer should be cleared.

Return

void

Parameters

configData: The configuration data associated with the module

struct fswModuleTemplateConfig¶

#include <fswModuleTemplate.h>

Top level structure for the sub-module routines.

Public Members

double dummy¶: [units] sample module variable declaration

double dumVector[3]¶: [units] sample vector variable

char dataOutMsgName[MAX_STAT_MSG_LENGTH]¶: The name of the output message.

int32_t dataOutMsgID¶: ID for the outgoing message.

char dataInMsgName[MAX_STAT_MSG_LENGTH]¶: The name of the Input message.

int32_t dataInMsgID¶: ID for the incoming message.

double inputVector[3]¶: [units] vector description

BSKLogger *bskLogger¶: BSK Logging.