A Tour of Cycstub

Since Cyclus version 1.3.1 the Cycstub CLI is included in a standard Cyclus installation.

This section will walk through the source files of the stub archetypes generated when a user invokes the cycstub utility. Cycstub can generate stubs for each of the agent types. The standard usage to generate the stubs for a Facility, Institution or Region, respectively, is:

cycstub --type facility :stublibrary:StubFacility
cycstub --type institution :stublibrary:StubInstitution
cycstub --type region :stublibrary:StubRegion

We will walk through StubFacility‘s source specifically because its the most complicated of the three.

StubFacility

The StubFacility provides the minimal interface that an archetype that derives from cyclus::Facility must provide. We’ll go through both the header (h) and implementation (cc) files in conjunction, starting at the top.

stub_facility.h has a single Cyclus-based include

#include "cyclus.h"

which includes most cyclus kernel headers as a convenience for new archetype developers. You’re more than welcome to include the specific kernel headers you need if you require a smaller executable.

Moving on in the header file we come to the class declaration inside the namespace of this specific module library, stublibrary, with standard Doxygen documentation strings.

namespace stublibrary {

/// @class StubFacility
/// ...

class StubFacility : public cyclus::Facility  {

which simply states that the StubFacility inherits from cyclus::Facility.

We then come to the constructor declaration in the header file

explicit StubFacility(cyclus::Context* ctx);

and definition in the implementation file

StubFacility::StubFacility(cyclus::Context* ctx) : cyclus::Facility(ctx) {};

The constructor takes a single cyclus::Context argument. The context is the mechanism by which agents can query and otherwise communicate with the simulation environment. Because the base cyclus::Agent class requires a cyclus::Context argument in its constructor, all derived classes must pass the argument down its constructor chain, as StubFacility does with its cyclus::Facility constructor above.

Continuing with the header file, we next come to the prime directive

#pragma cyclus

In short, the prime directive allows an archetype developer to use the Cyclus preprocessor to autogenerate many member functions that are required for Cyclus features related to initialization and restart capabilities. For a further explanation, see Using the Cyclus Preprocessor.

The next line in stub_facility.h is also related to the preprocessor’s ability to help automate some documentation:

#pragma cyclus note {"doc": "A stub facility is provided as a skeleton " \
                            "for the design of new facility agents."}

Again, #pragma cyclus note is explained further in Using the Cyclus Preprocessor.

Continuing along, we reach the final three member functions, each of which are defined on the base cyclus::Agent class and are overrode by the StubFacility.

str

The declaration

virtual std::string str();

and implementation

std::string StubFacility::str() {
  return Facility::str();
}

of the str method allows the StubFacility to customize its string representation, which is printed at a variety of cyclus::Logger logging levels, which is explained further in Logging.

Tick

The declaration

virtual void Tick();

and implementation

void StubFacility::Tick() {}

of the Tick member function allows the StubFacility to act during the tick agent phase.

Tock

The declaration

virtual void Tock();

and implementation

void StubFacility::Tock() {}

of the Tock member function allows the StubFacility to act during the tock agent phase.