CYCLUS
Loading...
Searching...
No Matches
cyclus::Region Class Reference

Detailed Description

The Region class is the abstract class/interface used by all region agents.

This is all that is known externally about Regions

Introduction

The Region type assists in defining the region-institution-facility hierarchy in Cyclus. A Region region is an actor associated with a set of institutions or facilities for which it is responsible. A Region 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 Region implementations.

Like all agent implementations, there are a number of implementations that are distributed as part of the core Cyclus application as well as implementations contributed by third-party developers. The links below describe additional parameters necessary for the complete definition of a region of that implementation.

Basic Functionality

All regions perform three major functions:

  1. Schedule the deployment of facilities by either
  2. Determining when new facilities need to be built, or
  3. Deferring to an Institution to make this determination.
  4. Manage the deployment of facilities by interacting with the Institutions to select a specific facility type and facility parameters

Different regional types will be required to fully define the first two functions while the third is a built-in capability for all region types. For instance, one may wish to include a region which has exponential growth as its driving factor for facility creation or one may wish to have pre-determined building order based on time step (e.g. the JAEA benchmark). Additionally, one may wish for there to be a one-to-one region-to-instituion deployment for simple agents and thus demand that each instiution simply build a facility when its region determines the facility's necessity. However, one may instead wish to have two competing instiutions in one region and have the institution which provides the best incentive to the region to build a required facility.

Available Core Implementation

  • NullRegion: This region is associated with a set of allowed facilities. It defers to an institution regarding facility deployment, making no demands on facility type or parameter (save the facility's allowability in the region). It makes no alterations to messages passed through it in either the up or down direction.

Definition at line 60 of file region.h.

#include <region.h>

Inheritance diagram for cyclus::Region:
cyclus::Agent cyclus::TimeListener cyclus::StateWrangler cyclus::Ider cyclus::Ider cyclus::Dummy

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)
 
 Region (Context *ctx)
 
virtual void Snapshot (DbInit di)
 
virtual Inventories SnapshotInv ()
 
virtual std::string str ()
 
virtual void Tick ()
 
virtual void Tock ()
 
virtual ~Region ()
 
- 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 AgentClone ()=0
 
Contextcontext () 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)
 
Agentparent () 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 (Region *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

◆ Region()

cyclus::Region::Region ( Context * ctx)

Default constructor for Region Class.

Definition at line 20 of file region.cc.

◆ ~Region()

virtual cyclus::Region::~Region ( )
inlinevirtual

Regions should not be indestructible.

Definition at line 69 of file region.h.

Member Function Documentation

◆ Build()

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

perform actions required when entering the simulation

Reimplemented from cyclus::Agent.

Definition at line 24 of file region.cc.

◆ Decommission()

void cyclus::Region::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 32 of file region.cc.

◆ EnterNotify()

void cyclus::Region::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 28 of file region.cc.

◆ InfileToDb()

virtual void cyclus::Region::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) {
// 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();
// ...
};
// ...
};
Datum * AddVal(const char *field, boost::spirit::hold_any val, std::vector< int > *shape=NULL)
Add an arbitrary field-value pair to the datum.
Definition datum.cc:22
void Record()
Record this datum to its Recorder.
Definition datum.cc:35
DbInit provides an interface for agents to record data to the output db that automatically injects th...
Definition db_init.h:14
Datum * NewDatum(std::string title)
Returns a new datum to be used exactly as the Context::NewDatum method.
Definition db_init.cc:12
The Facility class is the abstract class/interface used by all facility agents.
Definition facility.h:68
virtual void InitFrom(QueryableBackend *b)
Intializes an agent's internal state from the database.
Definition facility.h:78
A class for extracting information from a given XML parser.
Definition infile_tree.h:22
virtual std::string GetString(std::string query, int index=0)
investigates the current status and returns a string representing the content of a query at a given i...
T OptionalQuery(InfileTree *tree, std::string query, T default_val)
a query method for optional parameters
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 72 of file region.h.

◆ InitFrom() [1/2]

virtual void cyclus::Region::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::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;
// ...
};
Meta data and results of a query.
T GetVal(std::string field, int row=0)
Convenience method for retrieving a value from a specific row and named field (column).
Interface implemented by backends that support rudimentary querying.
Warning
Agents should NOT create any resource objects in this function.

Reimplemented from cyclus::Agent.

Definition at line 75 of file region.h.

◆ InitFrom() [2/2]

void cyclus::Region::InitFrom ( Region * m)
protected

Definition at line 16 of file region.cc.

◆ InitInv()

virtual void cyclus::Region::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"]);
// ...
};
// ...
};
ResBuf is a helper class that provides semi-automated management of a collection of resources (e....
Definition res_buf.h:62
std::map< std::string, std::vector< Resource::Ptr > > Inventories
map<inventory_name, vector<resources_in_inventory> >.
Definition agent.h:38
Warning
agents should not modify any state outside the container filling

Implements cyclus::Agent.

Definition at line 80 of file region.h.

◆ Snapshot()

virtual void cyclus::Region::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) {
di.NewDatum("MyAgentTable1")
->AddVal("recipe", recipe)
->AddVal("in_commod", in_commod)
->AddVal("cap", cap)
->Record();
// ...
};
std::string recipe;
std::string in_commod;
double cap;
// ...
};
virtual void Snapshot(DbInit di)
Snapshots agent-internal state to the database via the DbInit var di.
Definition facility.h:81
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 78 of file region.h.

◆ SnapshotInv()

virtual Inventories cyclus::Region::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::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;
};
// ...
};
std::vector< Resource::Ptr > ResVec
Definition res_buf.h:21
Warning
This function MUST NOT modify the agent's internal state.

Implements cyclus::Agent.

Definition at line 82 of file region.h.

◆ str()

std::string cyclus::Region::str ( )
virtual

every agent should be able to print a verbose description

Reimplemented from cyclus::Agent.

Definition at line 37 of file region.cc.

◆ Tick()

virtual void cyclus::Region::Tick ( )
inlinevirtual

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

Parameters
timeis the current simulation timestep

Implements cyclus::TimeListener.

Definition at line 94 of file region.h.

◆ Tock()

virtual void cyclus::Region::Tock ( )
inlinevirtual

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

Parameters
timeis the current simulation timestep

Implements cyclus::TimeListener.

Definition at line 96 of file region.h.


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