CYCLUS
region.h
Go to the documentation of this file.
1 #ifndef CYCLUS_SRC_REGION_H_
2 #define CYCLUS_SRC_REGION_H_
3 
4 #include <set>
5 
6 #include "time_listener.h"
7 #include "infile_tree.h"
8 
9 namespace cyclus {
10 
11 /// @class Region
12 ///
13 /// The Region class is the abstract class/interface used by all
14 /// region agents
15 ///
16 /// This is all that is known externally about Regions
17 ///
18 /// @section intro Introduction
19 /// The Region type assists in defining the region-institution-facility
20 /// hierarchy in Cyclus. A Region region is an actor associated with a set
21 /// of institutions or facilities for which it is responsible. A Region may
22 /// be used to adjust preferences in the ResourceExchange to make material
23 /// routing decisions based on interfacility relationships. Deployment is a
24 /// primary differentiator between different Region implementations.
25 ///
26 /// Like all agent implementations, there are a number of implementations
27 /// that are distributed as part of the core Cyclus application as well
28 /// as implementations contributed by third-party developers. The links
29 /// below describe additional parameters necessary for the complete
30 /// definition of a region of that implementation.
31 ///
32 /// @section functionality Basic Functionality
33 /// All regions perform three major functions:
34 ///
35 /// -# Schedule the deployment of facilities by either
36 /// -# Determining when new facilities need to be built, or
37 /// -# Deferring to an Institution to make this determination.
38 /// -# Manage the deployment of facilities by interacting with the
39 /// Institutions to select a specific facility type and facility
40 /// parameters
41 ///
42 /// Different regional types will be required to fully define the first
43 /// two functions while the third is a built-in capability for all region
44 /// types. For instance, one may wish to include a region which has
45 /// exponential growth as its driving factor for facility creation or one
46 /// may wish to have pre-determined building order based on time step
47 /// (e.g. the JAEA benchmark). Additionally, one may wish for there to be
48 /// a one-to-one region-to-instituion deployment for simple agents and
49 /// thus demand that each instiution simply build a facility when its
50 /// region determines the facility's necessity. However, one may instead
51 /// wish to have two competing instiutions in one region and have the
52 /// institution which provides the best incentive to the region to build
53 /// a required facility.
54 /// @section availableCoreImpl Available Core Implementation
55 /// - NullRegion: This region is associated with a set of allowed
56 /// facilities. It defers to an institution regarding facility
57 /// deployment, making no demands on facility type or parameter (save the
58 /// facility's allowability in the region). It makes no alterations to
59 /// messages passed through it in either the up or down direction.
60 class Region : public Agent, public TimeListener {
61  // --------------------
62  // all MODEL classes have these members
63  // --------------------
64  public:
65  /// Default constructor for Region Class
66  Region(Context* ctx);
67 
68  /// Regions should not be indestructible.
69  virtual ~Region() {}
70 
71  // DO NOT call Agent class implementation of this method
72  virtual void InfileToDb(InfileTree* qe, DbInit di) {}
73 
74  // DO NOT call Agent class implementation of this method
75  virtual void InitFrom(QueryableBackend* b) {}
76 
77  // DO NOT call Agent class implementation of this method
78  virtual void Snapshot(DbInit di) {}
79 
80  virtual void InitInv(Inventories& inv) {}
81 
82  virtual Inventories SnapshotInv() { return Inventories(); }
83 
84  /// perform actions required when entering the simulation
85  virtual void Build(Agent* parent);
86 
87  virtual void EnterNotify();
88 
89  virtual void Decommission();
90 
91  /// every agent should be able to print a verbose description
92  virtual std::string str();
93 
94  virtual void Tick() {}
95 
96  virtual void Tock() {}
97 
98  protected:
99  void InitFrom(Region* m);
100 };
101 
102 } // namespace cyclus
103 
104 #endif // CYCLUS_SRC_REGION_H_
virtual Inventories SnapshotInv()
Snapshots an agent&#39;s resource inventories to the database.
Definition: region.h:82
virtual std::string str()
every agent should be able to print a verbose description
Definition: region.cc:37
virtual void InitInv(Inventories &inv)
Provides an agent&#39;s initial inventory of resources before a simulation begins.
Definition: region.h:80
double b(int nuc)
Computes the scattering length [cm] from the coherent and incoherent components.
Definition: pyne.cc:11180
virtual void InitFrom(QueryableBackend *b)
Intializes an agent&#39;s internal state from the database.
Definition: region.h:75
The Region class is the abstract class/interface used by all region agents.
Definition: region.h:60
A class for extracting information from a given XML parser.
Definition: infile_tree.h:22
virtual void Tock()
Simulation agents do their end-of-timestep activities in the Tock method.
Definition: region.h:96
virtual void Snapshot(DbInit di)
Snapshots agent-internal state to the database via the DbInit var di.
Definition: region.h:78
virtual void Build(Agent *parent)
perform actions required when entering the simulation
Definition: region.cc:24
std::map< std::string, std::vector< Resource::Ptr > > Inventories
map<inventory_name, vector<resources_in_inventory> >.
Definition: agent.h:35
virtual void InfileToDb(InfileTree *qe, DbInit di)
Translates info for the agent from an input file to the database by reading parameters from the passe...
Definition: region.h:72
virtual void Tick()
Simulation agents do their beginning-of-timestep activities in the Tick method.
Definition: region.h:94
Region(Context *ctx)
Default constructor for Region Class.
Definition: region.cc:20
DbInit provides an interface for agents to record data to the output db that automatically injects th...
Definition: db_init.h:14
virtual void EnterNotify()
Called to give the agent an opportunity to register for services (e.g.
Definition: region.cc:28
The TimeListener class is an inheritable class for any Agent that requires knowlege of ticks and tock...
Definition: time_listener.h:23
A simulation context provides access to necessary simulation-global functions and state...
Definition: context.h:128
The abstract base class used by all types of agents that live and interact in a simulation.
Definition: agent.h:51
taken directly from OsiSolverInterface.cpp on 2/17/14 from https://projects.coin-or.org/Osi/browser/trunk.
Definition: agent.cc:14
Agent * parent() const
Returns parent of this agent. Returns NULL if the agent has no parent.
Definition: agent.h:375
virtual void Decommission()
Decommissions the agent, removing it from the simulation.
Definition: region.cc:32
virtual ~Region()
Regions should not be indestructible.
Definition: region.h:69
Interface implemented by backends that support rudimentary querying.