CYCLUS
matl_sell_policy.h
Go to the documentation of this file.
1 #ifndef CYCLUS_SRC_TOOLKIT_MATL_SELL_POLICY_H_
2 #define CYCLUS_SRC_TOOLKIT_MATL_SELL_POLICY_H_
3 
4 #include <string>
5 
6 #include "composition.h"
7 #include "material.h"
8 #include "res_buf.h"
9 #include "trader.h"
10 
11 namespace cyclus {
12 namespace toolkit {
13 
14 /// MatlSellPolicy performs semi-automatic inventory management of a material
15 /// buffer by making offers and trading away materials in an attempt to empty
16 /// the buffer's inventory every time step.
17 ///
18 /// For simple behavior, policies virtually eliminate the need to write any code
19 /// for resource exchange. Just assign a few policies to work with a few buffers
20 /// and focus on writing the physics and other behvavior of your agent. Typical
21 /// usage goes something like this:
22 ///
23 /// @code
24 /// class YourAgent : public Facility {
25 /// public:
26 /// ...
27 ///
28 /// void EnterNotify() {
29 /// Facility::EnterNotify(); // always do this first
30 ///
31 /// policy_.Init(this, &outbuf_, "outbuf-label").Set(outcommod).Start();
32 /// }
33 /// ...
34 ///
35 /// private:
36 /// MatlSellPolicy policy_;
37 /// ResBuf<Material> outbuf_;
38 /// ...
39 /// }
40 /// @endcode
41 ///
42 /// The policy needs to be initialized with its owning agent and the material
43 /// buffer that is is managing. It also needs to be activated by calling the
44 /// Start function for it to begin participation in resource exchange. And
45 /// don't forget to add some commodities to offer on by calling Set. All policy
46 /// configuration should usually occur in the agent's EnterNotify member
47 /// function.
48 ///
49 /// @warn When a policy's managing agent is deallocated, you MUST either
50 /// call the policy's Stop function or delete the policy. Otherwise SEGFAULT.
51 class MatlSellPolicy : public Trader {
52  public:
53  /// Creates an uninitialized policy. The Init function MUST be called before
54  /// anything else is done with the policy.
56 
57  virtual ~MatlSellPolicy();
58 
59  /// Configures the policy to keep buf empty every time step by offering away
60  /// as much material as possible. If quantize is greater than zero, the
61  /// policy will make exclusive, integral quantize kg offers. Otherwise, a
62  /// single offer will be sent each time step to empty the buffer's entire
63  /// inventory.
64  /// @param manager the agent
65  /// @param buf the resource buffer
66  /// @param name a unique name identifying this policy
67  /// @param throughput a maximum throughput per time step for material leaving
68  /// buf
69  /// @ignore_comp ignore the composition of material in buf. When making bids,
70  /// requested material compositions will be used. When making trades,
71  /// material in the buffer will have its composition transmuted to match the
72  /// requested material.
73  /// @param quantize If quantize is greater than zero, the policy will make
74  /// exclusive, integral quantize kg bids. Otherwise, single bids will
75  /// be sent matching the requested quantity.
76  /// @{
77  MatlSellPolicy& Init(Agent* manager, ResBuf<Material>* buf, std::string name);
78  MatlSellPolicy& Init(Agent* manager, ResBuf<Material>* buf, std::string name,
79  double throughput);
80  MatlSellPolicy& Init(Agent* manager, ResBuf<Material>* buf, std::string name,
81  bool ignore_comp);
82  MatlSellPolicy& Init(Agent* manager, ResBuf<Material>* buf, std::string name,
83  double throughput, bool ignore_comp);
84  MatlSellPolicy& Init(Agent* manager, ResBuf<Material>* buf, std::string name,
85  double throughput, bool ignore_comp,
86  double quantize);
87  /// @}
88 
89  /// Instructs the policy to empty its buffer with offers on the given
90  /// commodity. This must be called at least once or the policy will do
91  /// nothing. The policy can offer on an arbitrary number of commodities by
92  /// calling Set multiple times.
93  MatlSellPolicy& Set(std::string commod);
94 
95  /// Registers this policy as a trader in the current simulation. This
96  /// function must be called for the policy to begin participating in resource
97  /// exchange. Init MUST be called prior to calling this function. Start is
98  /// idempotent.
99  void Start();
100 
101  /// Unregisters this policy as a trader in the current simulation. This
102  /// function need only be called if a policy is to be stopped *during* a
103  /// simulation (it is not required to be called explicitly at the end). Stop
104  /// is idempotent.
105  void Stop();
106 
107  /// the current (total) limit on transactions, i.e., the quantity of resources
108  /// that can be transacted in a time step
109  double Limit() const;
110 
111  /// whether trades will be denoted as exclusive or not
112  inline bool Excl() const { return quantize_ > 0; }
113 
114  /// Trader Methods
115  /// @{
116  virtual std::set<BidPortfolio<Material>::Ptr> GetMatlBids(
117  CommodMap<Material>::type& commod_requests);
118  virtual void GetMatlTrades(
119  const std::vector<Trade<Material> >& trades,
120  std::vector<std::pair<Trade<Material>, Material::Ptr> >& responses);
121  /// }@
122 
123  private:
124  void set_quantize(double x);
125  void set_throughput(double x);
126  void set_ignore_comp(bool x);
127 
128  ResBuf<Material>* buf_;
129  std::set<std::string> commods_;
130  double quantize_;
131  double throughput_;
132  std::string name_;
133  bool ignore_comp_;
134 };
135 
136 } // namespace toolkit
137 } // namespace cyclus
138 
139 #endif
MatlSellPolicy & Set(std::string commod)
Instructs the policy to empty its buffer with offers on the given commodity.
std::map< std::string, std::vector< Request< T > * > > type
bool Excl() const
whether trades will be denoted as exclusive or not
void Start()
Registers this policy as a trader in the current simulation.
boost::shared_ptr< Material > Ptr
Definition: material.h:75
MatlSellPolicy & Init(Agent *manager, ResBuf< Material > *buf, std::string name)
Configures the policy to keep buf empty every time step by offering away as much material as possible...
std::string name(int nuc)
Definition: pyne.cc:2940
A simple API for agents that wish to exchange resources in the simulation.
Definition: trader.h:24
MatlSellPolicy performs semi-automatic inventory management of a material buffer by making offers and...
virtual void GetMatlTrades(const std::vector< Trade< Material > > &trades, std::vector< std::pair< Trade< Material >, Material::Ptr > > &responses)
default implementation for responding to material trades
virtual std::set< BidPortfolio< Material >::Ptr > GetMatlBids(CommodMap< Material >::type &commod_requests)
Trader Methods.
virtual Agent * manager()
Definition: trader.h:28
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
A Trade is a simple container that associates a request for a resource with a bid for that resource...
Definition: trade.h:16
double Limit() const
the current (total) limit on transactions, i.e., the quantity of resources that can be transacted in ...
ResBuf is a helper class that provides semi-automated management of a collection of resources (e...
Definition: res_buf.h:62
void Stop()
Unregisters this policy as a trader in the current simulation.
MatlSellPolicy()
Creates an uninitialized policy.