Detailed Description

The abstract base class used by all types of agents that live and interact in a simulation.

There are several functions that must be implemented in support of simulation initialization, snapshotting and restart: InfileToDb, InitFrom(QueryableBackend*), Snapshot, SnapshotInv, and InitInv. These functions all do inter-related things. Notably, the InfileToDb, InitFrom, and Snapshot functions must all write/read to/from the same database tables (and table schemas).

Definition at line 49 of file agent.h.

#include <agent.h>

Inheritance diagram for cyclus::Agent:

Public Member Functions
virtual void	AdjustMatlPrefs (PrefMap< Material >::type &prefs)

virtual void	AdjustProductPrefs (PrefMap< Product >::type &prefs)

	Agent (Context *ctx)

bool	AncestorOf (Agent *other)

virtual Json::Value	annotations ()

virtual void	Build (Agent *parent)

virtual void	BuildNotify (Agent *m)

const std::set< Agent * > &	children () const

virtual Agent *	Clone ()=0

Context *	context () const

bool	DecendentOf (Agent *other)

virtual void	Decommission ()

virtual void	DecomNotify (Agent *m)

const int	enter_time () const

virtual void	EnterNotify ()

const int	exit_time () const

std::vector< std::string >	GetTreePrintOuts (Agent *m)

virtual const int	id () const

bool	InFamilyTree (Agent *other)

virtual void	InfileToDb (InfileTree *qe, DbInit di)

virtual void	InitFrom (QueryableBackend *b)

virtual void	InitInv (Inventories &inv)=0

const std::string	kind () const

const int	lifetime () const

void	lifetime (int n_timesteps)

void	lifetime_force (int n_timesteps)

Agent *	parent () const

const int	parent_id () const

std::string	PrintChildren ()

const std::string	prototype () const

void	prototype (std::string p)

virtual std::string	schema ()

virtual void	Snapshot (DbInit di)=0

virtual Inventories	SnapshotInv ()=0

std::string	spec ()

void	spec (std::string new_impl)

virtual std::string	str ()

virtual std::string	version ()

virtual	~Agent ()

Protected Member Functions
virtual std::string	InformErrorMsg (std::string msg)

void	InitFrom (Agent *m)

Protected Attributes
std::string	kind_

Constructor & Destructor Documentation

◆ Agent()

cyclus::Agent::Agent ( Context * ctx )

Creates a new agent that is managed by the given context.

Note that the context takes ownership of its agents' memory and so agents should generally never be created on the stack.

Definition at line 59 of file agent.cc.

◆ ~Agent()

cyclus::Agent::~Agent ( )

virtual

Removes references to self from simulation context, parent, children, etc.

All subclass destructors should also be virtual.

Definition at line 72 of file agent.cc.

Member Function Documentation

◆ AdjustMatlPrefs()

virtual void cyclus::Agent::AdjustMatlPrefs ( PrefMap< Material >::type & prefs )

inlinevirtual

default implementation for material preferences.

Reimplemented in cyclus::Facility.

Definition at line 325 of file agent.h.

◆ AdjustProductPrefs()

virtual void cyclus::Agent::AdjustProductPrefs ( PrefMap< Product >::type & prefs )

inlinevirtual

default implementation for material preferences.

Reimplemented in cyclus::Facility.

Definition at line 328 of file agent.h.

◆ AncestorOf()

bool cyclus::Agent::AncestorOf ( Agent * other )

returns true if this agent is an ancestor of an other agent (i.e., resides above an other agent in the family tree)

Parameters

other the other agent

Definition at line 129 of file agent.cc.

◆ annotations()

virtual Json::Value cyclus::Agent::annotations ( )

inlinevirtual

Returns an agent's json annotations for all state variables and any other information the developer wishes to provide.

All concrete agents should override this function.

Definition at line 340 of file agent.h.

◆ Build()

void cyclus::Agent::Build ( Agent * parent )

virtual

Called when the agent enters the smiulation as an active participant and is only ever called once.

Agents should NOT register for services (such as ticks/tocks and resource exchange) in this function. If agents implement this function, they must call their superclass' Build function at the BEGINING of their Build function.

Parameters

parent this agent's parent. NULL if this agent has no parent.

Reimplemented in cyclus::Facility, cyclus::Institution, and cyclus::Region.

Definition at line 153 of file agent.cc.

◆ BuildNotify()

virtual void cyclus::Agent::BuildNotify ( Agent * m )

inlinevirtual

Called when a new child of this agent has just been built.

It is possible for this function to be called before the simulation has started when initially existing agents are being setup.

Definition at line 313 of file agent.h.

◆ children()

const std::set< Agent * > & cyclus::Agent::children ( ) const

inline

Returns a list of children this agent has.

Definition at line 412 of file agent.h.

◆ Clone()

virtual Agent * cyclus::Agent::Clone ( )

pure virtual

Returns a newly created/allocated prototype that is an exact copy of this.

All initialization and state cloning operations should be done in the agent's InitFrom(Agent*) function. The new agent instance should NOT be created using a default copy-constructor. New agent instances should generally be created using a constructor that takes a single Context argument (the same context of the agent being cloned). Example:

class MyAgentClass : virtual public Agent {
  ...
 
  virtual Agent* Clone() {
    MyAgentClass* m = new MyAgentClass(context());
    m->InitFrom(this);
    return m;
  };
 
  ...
};

Implements cyclus::StateWrangler.

Implemented in cyclus::Dummy.

◆ context()

Context * cyclus::Agent::context ( ) const

inline

Returns this agent's simulation context.

Definition at line 367 of file agent.h.

◆ DecendentOf()

bool cyclus::Agent::DecendentOf ( Agent * other )

returns true if this agent is an decendent of an other agent (i.e., resides below an other agent in the family tree)

Parameters

other the other agent

Definition at line 139 of file agent.cc.

◆ Decommission()

void cyclus::Agent::Decommission ( )

virtual

Decommissions the agent, removing it from the simulation.

Results in destruction of the agent object. If agents write their own Decommission function, they must call their superclass' Decommission function at the END of their Decommission function.

Reimplemented in cyclus::Facility, cyclus::Institution, and cyclus::Region.

Definition at line 182 of file agent.cc.

◆ DecomNotify()

virtual void cyclus::Agent::DecomNotify ( Agent * m )

inlinevirtual

Called when a child of this agent is about to be decommissioned.

Definition at line 316 of file agent.h.

◆ enter_time()

const int cyclus::Agent::enter_time ( ) const

inline

Returns the time step at which this agent's Build function was called (-1 if the agent has never been built).

Definition at line 381 of file agent.h.

◆ EnterNotify()

void cyclus::Agent::EnterNotify ( )

virtual

Called to give the agent an opportunity to register for services (e.g.

ticks/tocks and resource exchange). Note that this may be called more than once, and so agents should track their registrations carefully. If agents implement this function, they must call their superclass's EnterNotify function at the BEGINNING of their EnterNotify function.

Reimplemented in cyclus::Facility, cyclus::Institution, and cyclus::Region.

Definition at line 166 of file agent.cc.

◆ exit_time()

const int cyclus::Agent::exit_time ( ) const

inline

Returns the default time step at which this agent will exit the simulation (-1 if the agent has an infinite lifetime).

Deomissioning happens at the end of a time step. With a lifetime of 1, we expect an agent to go through only 1 entire time step. In this case, the agent should be decommissioned on the same time step it was created. Therefore, for agents with non-infinite lifetimes, the exit_time will be the enter time plus its lifetime less 1.

Definition at line 405 of file agent.h.

◆ GetTreePrintOuts()

std::vector< std::string > cyclus::Agent::GetTreePrintOuts ( Agent * m )

returns a vector of strings representing the parent-child tree at the node for Agent m

Parameters

m	the agent node to base as the root of this print tree

Definition at line 208 of file agent.cc.

◆ id()

virtual const int cyclus::Agent::id ( ) const

inlinevirtual

The agent instance's unique ID within a simulation.

Implements cyclus::Ider.

Definition at line 352 of file agent.h.

◆ InFamilyTree()

bool cyclus::Agent::InFamilyTree ( Agent * other )

returns true if this agent is in the parent-child family tree of an other agent

Parameters

other the other agent

Definition at line 149 of file agent.cc.

◆ InfileToDb()

void cyclus::Agent::InfileToDb	(	InfileTree *	qe,
		DbInit	di )

virtual

Translates info for the agent from an input file to the database by reading parameters from the passed InfileTree (parsed from xml) and recording data via the DbInit variable.

The simulation id and agent id are automatically injected in all data transfered to the database through DbInit. This function must be implemented by all agents. This function must call the superclass' InfileToDb function before doing any other work.

Agent parameters in the InfileTree are scoped in the "agent/*&zwj;/" path. The superclass InitFrom expects the scope InfileTree passed to it to be unchanged from the agent's InfileTree arg.

Example:

class MyAgentClass : virtual public cyclus::Facility {
  // ...
 
  void InfileToDb(cyclus::InfileTree* tree, cyclus::DbInit di) {
    cyclus::Facility::InitFrom(tree);
 
    // now do MyAgentClass' initialitions, e.g.:
    tree = tree->Query("agent/*"); // rescope the InfileTree
 
    // retrieve all agent params
    std::string recipe = tree->GetString("recipe");
    std::string in_commod = tree->GetString("in_commod");
    double cap = cyclus::Query<double>(tree, "cap");
    di.NewDatum("MyAgentTable1")
      ->AddVal("recipe", recipe)
      ->AddVal("in_commod", in_commod)
      ->AddVal("cap", cap)
      ->Record();
    // ...
  };
 
  // ...
};

Warning: because 'SimId' 'SimTime', and 'AgentId' fields are automatically injected, those labels cannot be used for any other fields.; this function MUST NOT modify the agent's state.

Implements cyclus::StateWrangler.

Reimplemented in cyclus::Facility, cyclus::Institution, and cyclus::Region.

Definition at line 36 of file agent.cc.

◆ InformErrorMsg()

std::string cyclus::Agent::InformErrorMsg ( std::string msg )

protectedvirtual

adds agent-specific information prefix to an error message

Definition at line 27 of file agent.cc.

◆ InitFrom() [1/2]

void cyclus::Agent::InitFrom ( Agent * m )

protected

Initializes a agent by copying parameters from the passed agent m.

This function must be implemented by all agents. This function must call the superclass' InitFrom function. The InitFrom function should only initialize this class' members - not inherited state. The superclass InitFrom should generally be called before any other work is done.

Parameters

m	the agent containing state that should be used to initialize this agent.

Example:

class MyAgentClass : virtual public cyclus::Facility {
  // ...
 
  void InitFrom(MyAgentClass* m) {
    cyclus::Facility::InitFrom(m); // call superclass' InitFrom
    // now do MyAgentClass' initialitions, e.g.:
    my_var_ = m->my_var_;
    // ...
  };
 
  // ...
};

Definition at line 19 of file agent.cc.

◆ InitFrom() [2/2]

void cyclus::Agent::InitFrom ( QueryableBackend * b )

virtual

Intializes an agent's internal state from the database.

Appropriate simulation id, agent id, and time filters are automatically included in all queries. If the agent is a direct subclass of the Agent class, than it should NOT call its superclass' InitFrom(QueryableBackend*) function. If, however, it is a subclasses other Agent subclasses (e.g. subclass of Facility, Region, etc.), then it MUST call its superclass' InitFrom(QueryableBackend*) function. Example:

class MyAgentClass : virtual public cyclus::Facility {
  // ...
 
  void InitFrom(cyclus::QueryableBackend* b) {
    cyclus::Facility::InitFrom(b);
 
    cyclus::QueryResult qr = b->Query("MyAgentTable1", NULL);
    recipe = qr.GetVal<std::string>("recipe");
    in_commod = qr.GetVal<std::string>("in_commod");
    cap = qr.GetVal<double>("cap");
 
    // ...
  };
 
  std::string recipe;
  std::string in_commod;
  double cap;
 
  // ...
};

Warning: Agents should NOT create any resource objects in this function.

Implements cyclus::StateWrangler.

Reimplemented in cyclus::Facility, cyclus::Institution, and cyclus::Region.

Definition at line 45 of file agent.cc.

◆ InitInv()

virtual void cyclus::Agent::InitInv ( Inventories & inv )

pure virtual

Provides an agent's initial inventory of resources before a simulation begins.

The resources are keyed in the same way as given in the agent's SnapshotInv function. Agents should iterate through each named inventory provided and populate their corresponding resource containers with the given resources.

class MyAgentClass : virtual public cyclus::Facility {
  // ...
 
  void InitInv(cyclus::Inventories& inv) {
    buf1.Push(inv["buf1"]);
    buf2.Push(inv["buf2"]);
 
    // ...
  };
 
  cyclus::toolkit::ResBuf<Material> buf1;
  cyclus::toolkit::ResBuf<Material> buf2;
 
  // ...
};

Warning: agents should not modify any state outside the container filling

Implemented in cyclus::Institution, and cyclus::Region.

◆ kind()

const std::string cyclus::Agent::kind ( ) const

inline

Returns a string that describes the agent subclass (e.g.

Region, Facility, etc.)

Definition at line 364 of file agent.h.

◆ lifetime() [1/2]

const int cyclus::Agent::lifetime ( ) const

inline

Returns the number of time steps this agent operates between building and decommissioning (-1 if the agent has an infinite lifetime).

Definition at line 395 of file agent.h.

◆ lifetime() [2/2]

void cyclus::Agent::lifetime ( int n_timesteps )

Sets the number of time steps this agent operates between building and decommissioning (-1 if the agent has an infinite lifetime).

This should generally only be called BEFORE an agent is added to a context as a prototype. Throws ValueError if the agent has already been deployed.

Definition at line 108 of file agent.cc.

◆ lifetime_force()

void cyclus::Agent::lifetime_force ( int n_timesteps )

Sets the number of time steps this agent operates between building and decommissioning (-1 if the agent has an infinite lifetime).

Definition at line 115 of file agent.cc.

◆ parent()

Agent * cyclus::Agent::parent ( ) const

inline

Returns parent of this agent. Returns NULL if the agent has no parent.

Definition at line 373 of file agent.h.

◆ parent_id()

const int cyclus::Agent::parent_id ( ) const

inline

Returns the id for this agent's parent.

Returns -1 if this agent has no parent.

Definition at line 377 of file agent.h.

◆ PrintChildren()

std::string cyclus::Agent::PrintChildren ( )

recursively prints the parent-child tree

Definition at line 193 of file agent.cc.

◆ prototype() [1/2]

const std::string cyclus::Agent::prototype ( ) const

inline

Returns the agent's prototype.

Definition at line 345 of file agent.h.

◆ prototype() [2/2]

void cyclus::Agent::prototype ( std::string p )

inline

Sets the agent's prototype.

This should generally NEVER be called explicitly by code outside the cyclus kernel.

Definition at line 349 of file agent.h.

◆ schema()

virtual std::string cyclus::Agent::schema ( )

inlinevirtual

Returns an agent's xml rng schema for initializing from input files.

All concrete agents should override this function. This must validate the same xml input that the InfileToDb function receives.

Implements cyclus::StateWrangler.

Definition at line 333 of file agent.h.

◆ Snapshot()

void cyclus::Agent::Snapshot ( DbInit di )

pure virtual

Snapshots agent-internal state to the database via the DbInit var di.

The simulation id , agent id, and the simulation time are automatically injected in all information transfered to the database through DbInit. If the agent is a direct subclass of the Agent class, than it should NOT call its superclass' Snapshot function. If, however, it subclasses other Agent subclasses (e.g. subclass of Facility, Region, etc.), then it MUST call its superclass' Snapshot function. Example:

class MyAgentClass : virtual public cyclus::Facility {
  // ...
 
  void Snapshot(cyclus::DbInit di) {
    cyclus::Facility::Snapshot(di);
 
    di.NewDatum("MyAgentTable1")
      ->AddVal("recipe", recipe)
      ->AddVal("in_commod", in_commod)
      ->AddVal("cap", cap)
      ->Record();
 
    // ...
  };
 
  std::string recipe;
  std::string in_commod;
  double cap;
 
  // ...
};

Warning: because 'SimId' 'SimTime', and 'AgentId' fields are automatically injected, those labels cannot be used for any other fields.; This function MUST NOT modify the agent's internal state.; Do not record any information via the context's NewDatum function.

Implements cyclus::StateWrangler.

Implemented in cyclus::Facility, cyclus::Institution, and cyclus::Region.

Definition at line 52 of file agent.cc.

◆ SnapshotInv()

virtual Inventories cyclus::Agent::SnapshotInv ( )

pure virtual

Snapshots an agent's resource inventories to the database.

The set of resources in each container should be stored under a string key unique for that container that will be used when re-initializing inventories for restarted simulations in the InitInv function.

class MyAgentClass : virtual public cyclus::Facility {
  // ...
 
  cyclus::Inventories SnapshotInv() {
    cyclus::Inventories invs;
    cyclus::toolkit::ResVec rs = buf1.PopNRes(buf1.count());
    buf1.Push(rs); // Snapshot must not change agent's state
    invs["buf1"] = rs;
    rs = buf2.PopNRes(buf2.count());
    buf2.Push(rs); // Snapshot must not change agent's state
    invs["buf2"] = rs;
 
    // ...
 
    return invs;
  };
 
  cyclus::toolkit::ResBuf<Material> buf1;
  cyclus::toolkit::ResBuf<Material> buf2;
 
  // ...
};

Warning: This function MUST NOT modify the agent's internal state.

Implemented in cyclus::Institution, and cyclus::Region.

◆ spec() [1/2]

std::string cyclus::Agent::spec ( )

inline

The string representation of the agent spec that uniquely identifies the concrete agent class/module.

See CEP21 for details..

Definition at line 356 of file agent.h.

◆ spec() [2/2]

void cyclus::Agent::spec ( std::string new_impl )

inline

Sets this agent's agent spec.

This should generally NEVER be called explicitly by code outside the cyclus kernel.

Definition at line 360 of file agent.h.

◆ str()

std::string cyclus::Agent::str ( )

virtual

Description of this agent.

Reimplemented in cyclus::Facility, cyclus::Institution, and cyclus::Region.

Definition at line 96 of file agent.cc.

◆ version()

virtual std::string cyclus::Agent::version ( )

inlinevirtual

Definition at line 63 of file agent.h.

Member Data Documentation

◆ kind_

std::string cyclus::Agent::kind_

protected

describes the agent subclass (e.g.

Region, Inst, etc.). The in-kernel subclasses must set this variable in their constructor(s).

Definition at line 447 of file agent.h.

The documentation for this class was generated from the following files:

Detailed Description

Public Member Functions

Protected Member Functions

Protected Attributes

Constructor & Destructor Documentation

◆ Agent()

◆ ~Agent()

Member Function Documentation

◆ AdjustMatlPrefs()

◆ AdjustProductPrefs()

◆ AncestorOf()

◆ annotations()

◆ Build()

◆ BuildNotify()

◆ children()

◆ Clone()

◆ context()

◆ DecendentOf()

◆ Decommission()

◆ DecomNotify()

◆ enter_time()

◆ EnterNotify()

◆ exit_time()

◆ GetTreePrintOuts()

◆ id()

◆ InFamilyTree()

◆ InfileToDb()

◆ InformErrorMsg()

◆ InitFrom() [1/2]

◆ InitFrom() [2/2]

◆ InitInv()

◆ kind()

◆ lifetime() [1/2]

◆ lifetime() [2/2]

◆ lifetime_force()

◆ parent()

◆ parent_id()

◆ PrintChildren()

◆ prototype() [1/2]

◆ prototype() [2/2]

◆ schema()

◆ Snapshot()

◆ SnapshotInv()

◆ spec() [1/2]

◆ spec() [2/2]

◆ str()

◆ version()

Member Data Documentation

◆ kind_