CYCLUS
mock_sim.h
Go to the documentation of this file.
1 #ifndef CYCLUS_SRC_MOCK_SIM_H_
2 #define CYCLUS_SRC_MOCK_SIM_H_
3 
4 #include "cyclus.h"
5 #include "sqlite_back.h"
6 #include "timer.h"
7 
8 namespace cyclus {
9 
10 class Source;
11 class Sink;
12 
13 /// MockAgent is a template for accumulating configuration information used to
14 /// generate a source or sink facility in a MockSimulation. All parameters
15 /// other than commod have defaults. After all desired configuration is
16 /// completed, the Finalize function MUST be called. All configure functions
17 /// return the MockAgent itself to enable chaining. Default configuration is:
18 ///
19 /// * no recipe - sources provide requested material, sinks take anything
20 /// * infinite per time step capacity
21 /// * start/deploy on time step zero
22 /// * infinite lifetime.
23 ///
24 /// For examples on how to use MockAgent, see the MockSim API documentation.
25 class MockAgent {
26  public:
27 
28  /// Initializes a MockAgent to create a source (is_source == true) or a
29  /// sink (is_source == false) in the provided simulation context. rec must be
30  /// the recorder used to initialize ctx and b must be a backend registered
31  /// with rec.
32  MockAgent(Context* ctx, Recorder* rec, SqliteBack* b, bool is_source);
33 
34  /// Sets the commodity to be offered/requested by the source/sink.
35  MockAgent commod(std::string commod);
36 
37  /// Sets the recipe to be offered/requested by the source/sink.
38  MockAgent recipe(std::string recipe);
39 
40  /// Sets the per time step capacity/throughput limit for provided/received
41  /// material in kg for the source/sink.
42  MockAgent capacity(double cap);
43 
44  /// Sets the time step in the simulation that the source/sink should be
45  /// deployed.
46  MockAgent start(int timestep);
47 
48  /// Sets the lifetime in time steps of the source/sink before it is
49  /// decommissioned.
50  MockAgent lifetime(int duration);
51 
52  /// Finalize MUST be called after configuration is complete to actually
53  /// create the source/sink agent (or schedule it to be built). The
54  /// auto-generated prototype name of the created prototype is returned to
55  /// support querying based on specific sources/sinks.
56  std::string Finalize();
57 
58  private:
59  static int nextid_;
60  bool source_;
61  std::string commod_;
62  std::string recipe_;
63  double cap_;
64  int start_;
65  int lifetime_;
66  std::string proto_;
67  Context* ctx_;
68  Recorder* rec_;
69  SqliteBack* back_;
70 };
71 
72 /// MockSim is a helper for running full simulations entirely in-code to test
73 /// archetypes/agents without having to deal with input files, output database
74 /// files, and other pieces of the full Cyclus stack. This is especially
75 /// convenient for writing unit-like tests (e.g. using gtest) for your
76 /// archetype's in-simulation behavior. Initialize the MockSim indicating the
77 /// archetype you want to test and the simulation duration. Then add any
78 /// number of sources and/or sinks to transact with your agent. They can have
79 /// specific recipes (or not) and their deployment and lifetime (before
80 /// decommissioning) can be specified too. Here is an example using the
81 /// agents:Source archetype in Cyclus as the tested agent:
82 ///
83 /// @code
84 ///
85 /// cyclus::CompMap m;
86 /// m[922350000] = .05;
87 /// m[922380000] = .95;
88 /// cyclus::Composition::Ptr fresh = cyclus::Composition::CreateFromMass(m);
89 ///
90 /// std::string config =
91 /// "<commod>enriched_u</commod>"
92 /// "<recipe_name>fresh_fuel</recipe_name>"
93 /// "<capacity>10</capacity>";
94 ///
95 /// int dur = 10;
96 /// cyclus::MockSim sim(cyclus::AgentSpec(":agents:Source"), config, dur);
97 /// sim.AddSink("enriched_u").Finalize();
98 /// sim.AddRecipe("fresh_fuel", fresh);
99 /// int src_id = sim.Run(); // capture the agent ID of the facility being tested
100 ///
101 /// @endcode
102 ///
103 /// Querying the results can be accomplished by getting a reference to the
104 /// in-memory database generated. Not all data that is present in normal
105 /// full-stack simulations is available. However, most of the key core tables
106 /// are fully available. Namely, the Transactions, Composition, Resources,
107 /// ResCreators, AgentEntry, and AgentExit tables are available. Any
108 /// custom-tables created by the tested archetype will also be available. Here
109 /// is a sample query and test you might write if using the googletest
110 /// framework:
111 ///
112 /// @code
113 ///
114 /// // return all transactions where our source facility is the sender
115 /// std::vector<cyclus::Cond> conds;
116 /// conds.push_back("SenderId", "==", src_id);
117 /// cyclus::QueryResult qr = sim.db().Query("Transactions", &conds);
118 /// int n_trans = qr.rows.size();
119 /// EXPECT_EQ(10, n_trans) << "expected 10 transactions, got " << n_trans;
120 ///
121 /// // reconstruct the material object for the first transaction
122 /// int res_id = qr.GetVal<int>("ResourceId", 0);
123 /// cyclus::Material::Ptr m = sim.GetMaterial(res_id);
124 /// EXPECT_DOUBLE_EQ(10, m->quantity());
125 ///
126 /// // confirm composition is as expected
127 /// cyclus::toolkit::MatQuery mq(m);
128 /// EXPECT_DOUBLE_EQ(0.5, mq.mass(922350000));
129 /// EXPECT_DOUBLE_EQ(9.5, mq.mass(922380000));
130 ///
131 /// @endcode
132 class MockSim {
133  public:
134  /// Creates and initializes a new empty mock simulation environment where
135  /// duration is the length of the simulation in time steps. An agent must be
136  /// specified before running an empty-constructed MockSim (i.e. manually
137  /// construct an agent using MockSim::context() and setting MockSim::agent.
138  MockSim(int duration);
139 
140  /// Creates and initializes a new mock simulation environment to test the
141  /// archetype identified by spec. config should contain the
142  /// archetype-specific xml snippet excluding the wrapping "<config>" and
143  /// "<[AgentName]>" tags. duration is the length of the simulation in time
144  /// steps.
145  MockSim(AgentSpec spec, std::string config, int duration);
146 
147  /// Creates and initializes a new mock simulation environment to test the
148  /// archetype identified by spec. config should contain the
149  /// archetype-specific xml snippet excluding the wrapping "<config>" and
150  /// "<[AgentName]>" tags. duration is the length of the simulation in time
151  /// steps. 'lifetime' is the lifetime of the agent being tested.
152  MockSim(AgentSpec spec, std::string config, int duration, int lifetime);
153 
154  ~MockSim();
155 
156  /// AddSource adds a source facility that can offer/provide material to the
157  /// archetype being tested. commod specifies the commodity the source will
158  /// offer on. AddSource can be called multiple times to generate many sources
159  /// for the simulation. The returned MockAgent object has several functions
160  /// that can be called to configure the source's behavior further. Don't
161  /// forget to call the MockAgent object's "Finalize" function when you are
162  /// done configuring it. MockAgent's functions support chaining:
163  ///
164  /// @code
165  ///
166  /// cyclus::MockSim sim(...);
167  /// sim.AddSource("fresh_mox")
168  /// .start(7).lifetime(3).recipe("mox_fuel")
169  /// .Finalize();
170  ///
171  /// @endcode
172  MockAgent AddSource(std::string commod);
173 
174  /// AddSink adds a sink facility that can request+receive material from the
175  /// archetype being tested. commod specifies the commodity the sink will
176  /// request on. AddSink can be called multiple times to generate many sinks
177  /// for the simulation. The returned MockAgent object has several functions
178  /// that can be called to configure the sink's behavior further. Don't
179  /// forget to call the MockAgent object's "Finalize" function when you are
180  /// done configuring it. MockAgent's functions support chaining:
181  ///
182  /// @code
183  ///
184  /// cyclus::MockSim sim(...);
185  /// sim.AddSink("spent_mox")
186  /// .start(7).lifetime(3).recipe("spent_fresh_mox")
187  /// .Finalize();
188  ///
189  /// @endcode
190  MockAgent AddSink(std::string commod);
191 
192  /// AddRecipe adds a recipe to the mock simulation environment (i.e. to the
193  /// simulation context). Any recipes that your archetype expects to find in
194  /// the simulation context must be added this way; if the xml configuration
195  /// snippet for the archetype being tested contains a recipe name, add it
196  /// with this function.
197  void AddRecipe(std::string name, Composition::Ptr c);
198 
199  /// Adds a dummy prototype to the simulation that can be used by
200  /// institutions and other agents for deployment/decommission testing.
201  void DummyProto(std::string name);
202 
203  /// Runs the simulation. This can only be called once. After the simulation
204  /// has been run, this MockSim object CANNOT be reused to run other
205  /// simulations. Run returns the agent ID for the agent being tested for
206  /// use in queries.
207  int Run();
208 
209  /// Reconstructs a material object from the simulation results database with
210  /// the given resource state id.
211  Material::Ptr GetMaterial(int resid);
212 
213  /// Reconstructs a product object from the simulation results database with
214  /// the given resource state id.
215  Product::Ptr GetProduct(int resid);
216 
217  /// Returns the underlying in-memory database containing results for
218  /// the simulation. Run must be called before the database will contain
219  /// anything.
220  SqliteBack& db();
221 
222  /// Returns the context for the mock simulation environment.
223  Context* context() {return &ctx_;}
224 
225  /// the agent being tested by the mock simulation environment.
227 
228  private:
229  Context ctx_;
230  Timer ti_;
231  Recorder rec_;
232  SqliteBack* back_;
233 };
234 
235 } // namespace cyclus
236 
237 #endif // CYCLUS_SRC_MOCK_SIM_H_
Context * context()
Returns the context for the mock simulation environment.
Definition: mock_sim.h:223
boost::shared_ptr< Composition > Ptr
Definition: composition.h:43
double b(int nuc)
Computes the scattering length [cm] from the coherent and incoherent components.
Definition: pyne.cc:11180
An Recorder backend that writes data to an sqlite database.
Definition: sqlite_back.h:17
boost::shared_ptr< Material > Ptr
Definition: material.h:75
std::string name(int nuc)
Definition: pyne.cc:2940
MockAgent is a template for accumulating configuration information used to generate a source or sink ...
Definition: mock_sim.h:25
boost::shared_ptr< Product > Ptr
Definition: product.h:24
MockAgent(Context *ctx, Recorder *rec, SqliteBack *b, bool is_source)
Initializes a MockAgent to create a source (is_source == true) or a sink (is_source == false) in the ...
Definition: mock_sim.cc:39
MockAgent lifetime(int duration)
Sets the lifetime in time steps of the source/sink before it is decommissioned.
Definition: mock_sim.cc:73
MockAgent commod(std::string commod)
Sets the commodity to be offered/requested by the source/sink.
Definition: mock_sim.cc:57
Collects and manages output data generation for the cyclus core and agents during a simulation...
Definition: recorder.h:45
MockAgent recipe(std::string recipe)
Sets the recipe to be offered/requested by the source/sink.
Definition: mock_sim.cc:61
std::string Finalize()
Finalize MUST be called after configuration is complete to actually create the source/sink agent (or ...
Definition: mock_sim.cc:78
MockAgent start(int timestep)
Sets the time step in the simulation that the source/sink should be deployed.
Definition: mock_sim.cc:69
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
MockAgent capacity(double cap)
Sets the per time step capacity/throughput limit for provided/received material in kg for the source/...
Definition: mock_sim.cc:65
Agent * agent
the agent being tested by the mock simulation environment.
Definition: mock_sim.h:226
MockSim is a helper for running full simulations entirely in-code to test archetypes/agents without h...
Definition: mock_sim.h:132
Controls simulation timestepping and inter-timestep phases.
Definition: timer.h:22