Recording Messages

Source Code

The python code shown below can be downloaded here.

Great, now that we have a functioning simulation where Basilisk modules are set up with their messages connected, how do we get access to the simulation data? This is done by creating recorder modules that will store a time history of the generated messages.

The figure above illustrates a sample Basilisk simulation. The single test module cModule1 has its output message connected to its input message. This creates a feedback loop that will cause the output message to change. See the module code to understand the underlying simple math. To record the message state at various time steps, recorder modules will be created that perform this task.

Note

The method of recording a message is the same, regardless if it is a C or C++ module, or the message has a C or C++ interface.

The simulation code is included below. As the recorded message data will be plotted in this script, the matplotlib library is included at the top, as well as the helper package unitTestSupport from Basilisk.utilities.

import sys
from Basilisk.utilities import SimulationBaseClass
from Basilisk.utilities import macros
from Basilisk.moduleTemplates import cModuleTemplate
from Basilisk.architecture import messaging

from Basilisk.utilities import unitTestSupport
import matplotlib.pyplot as plt


def run():
    """
    Illustration of recording messages
    """

    #  Create a sim module as an empty container
    scSim = SimulationBaseClass.SimBaseClass()

    #  create the simulation process
    dynProcess = scSim.CreateNewProcess("dynamicsProcess")

    # create the dynamics task and specify the integration update time
    dynProcess.addTask(scSim.CreateNewTask("dynamicsTask", macros.sec2nano(1.)))

    # create modules
    mod1 = cModuleTemplate.cModuleTemplateConfig()
    mod1Wrap = scSim.setModelDataWrap(mod1)
    mod1Wrap.ModelTag = "cModule1"
    scSim.AddModelToTask("dynamicsTask", mod1Wrap, mod1)
    mod1.dataInMsg.subscribeTo(mod1.dataOutMsg)

    # setup message recording
    msgRec = mod1.dataOutMsg.recorder()
    scSim.AddModelToTask("dynamicsTask", msgRec)
    msgRec2 = mod1.dataOutMsg.recorder(macros.sec2nano(20.))
    scSim.AddModelToTask("dynamicsTask", msgRec2)

    #  initialize Simulation:
    scSim.InitializeSimulation()

    #   configure a simulation stop time time and execute the simulation run
    scSim.ConfigureStopTime(macros.sec2nano(60.0))
    scSim.ExecuteSimulation()

    # plot recorded data
    plt.close("all")
    plt.figure(1)
    figureList = {}
    for idx in range(3):
        plt.plot(msgRec.times() * macros.NANO2SEC, msgRec.dataVector[:, idx],
                 color=unitTestSupport.getLineColor(idx, 3),
                 label='$x_{' + str(idx) + '}$')
        plt.plot(msgRec2.times() * macros.NANO2SEC, msgRec2.dataVector[:, idx],
                 '--',
                 color=unitTestSupport.getLineColor(idx, 3),
                 label=r'$\hat x_{' + str(idx) + '}$')
    plt.legend(loc='lower right')
    plt.xlabel('Time [sec]')
    plt.ylabel('Module Data [units]')
    if "pytest" not in sys.modules:
        plt.show()
    figureList["bsk-4"] = plt.figure(1)
    plt.close("all")

    return figureList


if __name__ == "__main__":
    run()

Adding a Message Recorder

After the single BSK module instance is created and added to the task list, new code is provided to set up the message recorders. The general syntax is as follows. Assume you want to record module.someOutMsg. Note that this message can be either an output or input message. The corresponding recorder module is created using:

someMsgRec = module.someOutMsg.recorder()
scSim.AddModelToTask("taskName", someMsgRec)

The first line in the code block above creates the BSK message recorder object which is setup to record someOutMsg. As with any Basilisk module, it next needs to be added to a task to be executed each update cycle. As is, the recorder is set up to record the message at the same frequency as the task list update frequency. If you want to reduce the number of data points being recorded, you can provide an option argument:

someMsgRec = module.someOutMsg.recorder(minUpdateTime)

Here minUpdateTime is the minimum time interval that must pass before this recorder object will record the message.

In the full script above, the recorder module msgRec is set up to record the message at the dynamicsTask update rate. In contrast, the module msgRec20 is setup to record the message only after 20s have passed. Note that the minUpdateTime argument must be provided again in nano-seconds.

That is all that is required to set up message recording. Next the code initializes the simulation and executes it.

Pulling the Recorded Message Data

After the simulation completes, the recorded data is stored inside the msgRec and msgRec20 recorders. To access the variables of the message, simply use msgRec.variable where variable is the message structure variable you seek to access. To access the array of time values where the message was recorded use msgRec.times(). A second time array is available that stores the times where the messages are written with msgRec.timesWritten(). Why two time arrays? Consider an output message that is only updated every 3s, but the message is being read and recorded every second. The .timesWritten() values will repeat until a new output message is created.

Module: cModuleTemplate output message only contains the array dataVector. In this simulation it is recorded at the rate of 1Hz in msgRec, and every 20s in the recorder msgRec20. The simulation creates the following plot:

Clearing the Message Recorder Data Log

Note that the messager recorder will continuously add message data to its internal data vectors. If you start and stop the simulation, pull the data, resume the simulation and so on, this message data recording process is cumulative. If you stop the simulation and want to clear the message recorder data log so that only new data is recorded, you can clear the message recorder module data buffer using the .clear() method. For example, assume a message recorder scRec has been setup and needs to be cleared, this is done with:

scRec.clear()