Detailed Description

The Institution class is the abstract class/interface used by all institution agents.

Introduction The Institution type assists in defining the

region-institution-facility hierarchy in Cyclus. A Institution institution is an actor associated with a set of facilities for which it is responsible. An Institution may be used to adjust preferences in the ResourceExchange to make material routing decisions based on interfacility relationships. Deployment is a primary differentiator between different Institution implementations.

Definition at line 29 of file institution.h.

#include <institution.h>

Inheritance diagram for cyclus::Institution:

Public Member Functions
virtual void	Build (Agent *parent)

virtual void	Decommission ()

virtual void	EnterNotify ()

virtual void	InfileToDb (InfileTree *qe, DbInit di)

virtual void	InitFrom (QueryableBackend *b)

virtual void	InitInv (Inventories &inv)

	Institution (Context *ctx)

virtual void	Snapshot (DbInit di)

virtual Inventories	SnapshotInv ()

virtual std::string	str ()

virtual void	Tick ()

virtual void	Tock ()

virtual	~Institution ()

Public Member Functions inherited from cyclus::Agent
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	BuildNotify (Agent *m)

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

virtual Agent *	Clone ()=0

Context *	context () const

bool	DecendentOf (Agent *other)

virtual void	DecomNotify (Agent *m)

const int	enter_time () const

const int	exit_time () const

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

virtual const int	id () const

bool	InFamilyTree (Agent *other)

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 ()

std::string	spec ()

void	spec (std::string new_impl)

virtual std::string	version ()

virtual	~Agent ()

Public Member Functions inherited from cyclus::TimeListener
virtual void	Decision ()

Protected Member Functions
void	InitFrom (Institution *m)

Protected Member Functions inherited from cyclus::Agent
virtual std::string	InformErrorMsg (std::string msg)

void	InitFrom (Agent *m)

Additional Inherited Members
Protected Attributes inherited from cyclus::Agent
std::string	kind_

Constructor & Destructor Documentation

◆ Institution()

cyclus::Institution::Institution ( Context * ctx )

Default constructor for Institution Class.

Definition at line 16 of file institution.cc.

◆ ~Institution()

cyclus::Institution::~Institution ( )

virtual

every agent should be destructable

Definition at line 20 of file institution.cc.

Member Function Documentation

◆ Build()

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

virtual

perform all tasks required when an inst enters the simulation

Reimplemented from cyclus::Agent.

Definition at line 35 of file institution.cc.

◆ Decommission()

void cyclus::Institution::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 from cyclus::Agent.

Definition at line 43 of file institution.cc.

◆ EnterNotify()

void cyclus::Institution::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 from cyclus::Agent.

Definition at line 39 of file institution.cc.

◆ InfileToDb()

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

inlinevirtual

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.

Reimplemented from cyclus::Agent.

Definition at line 41 of file institution.h.

◆ InitFrom() [1/2]

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

protected

Definition at line 23 of file institution.cc.

◆ InitFrom() [2/2]

virtual void cyclus::Institution::InitFrom ( QueryableBackend * b )

inlinevirtual

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.

Reimplemented from cyclus::Agent.

Definition at line 44 of file institution.h.

◆ InitInv()

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

inlinevirtual

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

Implements cyclus::Agent.

Definition at line 49 of file institution.h.

◆ Snapshot()

virtual void cyclus::Institution::Snapshot ( DbInit di )

inlinevirtual

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::Agent.

Definition at line 47 of file institution.h.

◆ SnapshotInv()

virtual Inventories cyclus::Institution::SnapshotInv ( )

inlinevirtual

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.

Implements cyclus::Agent.

Definition at line 51 of file institution.h.

◆ str()

std::string cyclus::Institution::str ( )

virtual

every agent should be able to print a verbose description

Reimplemented from cyclus::Agent.

Definition at line 27 of file institution.cc.

◆ Tick()

virtual void cyclus::Institution::Tick ( )

inlinevirtual

Simulation agents do their beginning-of-timestep activities in the Tick method.

Parameters

time	is the current simulation timestep

Implements cyclus::TimeListener.

Definition at line 63 of file institution.h.

◆ Tock()

void cyclus::Institution::Tock ( )

virtual

Simulation agents do their end-of-timestep activities in the Tock method.

Parameters

time	is the current simulation timestep

Implements cyclus::TimeListener.

Definition at line 48 of file institution.cc.

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

Detailed Description

Introduction The Institution type assists in defining the

Public Member Functions

Protected Member Functions

Additional Inherited Members

Constructor & Destructor Documentation

◆ Institution()

◆ ~Institution()

Member Function Documentation

◆ Build()

◆ Decommission()

◆ EnterNotify()

◆ InfileToDb()

◆ InitFrom() [1/2]

◆ InitFrom() [2/2]

◆ InitInv()

◆ Snapshot()

◆ SnapshotInv()

◆ str()

◆ Tick()

◆ Tock()