CYCLUS
matl_buy_policy.h
Go to the documentation of this file.
1 #ifndef CYCLUS_SRC_TOOLKIT_MATL_BUY_POLICY_H_
2 #define CYCLUS_SRC_TOOLKIT_MATL_BUY_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 /// MatlBuyPolicy performs semi-automatic inventory management of a material
15 /// buffer by making requests and accepting materials in an attempt to fill the
16 /// buffer fully every time step according to an (s, S) inventory policy (see
17 /// [1]).
18 ///
19 /// For simple behavior, policies virtually eliminate the need to write any code
20 /// for resource exchange. Just assign a few policies to work with a few buffers
21 /// and focus on writing the physics and other behvavior of your agent. Typical
22 /// usage goes something like this:
23 ///
24 /// @code
25 /// class YourAgent : public cyclus::Facility {
26 /// public:
27 /// ...
28 ///
29 /// void EnterNotify() {
30 /// cyclus::Facility::EnterNotify(); // always do this first
31 ///
32 /// policy_.Init(this, &inbuf_, "inbuf-label").Set(incommod, comp).Start();
33 /// }
34 /// ...
35 ///
36 /// private:
37 /// MatlBuyPolicy policy_;
38 /// ResBuf<Material> inbuf_;
39 /// ...
40 /// }
41 /// @endcode
42 ///
43 /// The policy needs to be initialized with its owning agent and the material
44 /// buffer that is is managing. It also needs to be activated by calling the
45 /// Start function for it to begin participation in resource exchange. And
46 /// don't forget to add some commodities to request by calling Set. All policy
47 /// configuration should usually occur in the agent's EnterNotify member
48 /// function.
49 ///
50 /// [1] Zheng, Yu-Sheng. "A simple proof for optimality of (s, S) policies in
51 /// infinite-horizon inventory systems." Journal of Applied Probability
52 /// (1991): 802-810.
53 ///
54 /// @warn When a policy's managing agent is deallocated, you MUST either
55 /// call the policy's Stop function or delete the policy. Otherwise SEGFAULT.
56 class MatlBuyPolicy : public Trader {
57  public:
58  /// Creates an uninitialized policy. The Init function MUST be called before
59  /// anything else is done with the policy.
60  MatlBuyPolicy();
61 
62  virtual ~MatlBuyPolicy();
63 
64  /// Configures the policy to keep buf filled to a certain fraction of its
65  /// capacity every time step.
66  /// @param manager the agent
67  /// @param buf the resource buffer
68  /// @param name a unique name identifying this policy
69  /// @param throughput a constraining value for total transaction quantities in
70  /// a single time step
71  /// @param fill_to the amount or fraction of inventory to order when placing
72  /// an order. This is equivalent to the S in an (s, S) inventory policy.
73  /// @param req_when_under place an request when the buf's quantity is less
74  /// than its capacity * fill_to (as a fraction). This is equivalent to the s
75  /// in an (s, S) inventory policy.
76  /// @param quantize If quantize is greater than zero, the policy will make
77  /// exclusive, integral quantize kg requests. Otherwise, single requests will
78  /// be sent to fill the buffer's empty space.
79  /// @warning, (s, S) policy values are ambiguous for buffers with a capacity
80  /// in (0, 1]. However that is a rare case.
81  /// @{
82  MatlBuyPolicy& Init(Agent* manager, ResBuf<Material>* buf, std::string name);
83  MatlBuyPolicy& Init(Agent* manager, ResBuf<Material>* buf, std::string name,
84  double throughput);
85  MatlBuyPolicy& Init(Agent* manager, ResBuf<Material>* buf, std::string name,
86  double fill_to, double req_when_under);
87  MatlBuyPolicy& Init(Agent* manager, ResBuf<Material>* buf, std::string name,
88  double throughput, double fill_to,
89  double req_when_under, double quantize);
90  /// @}
91 
92  /// Instructs the policy to fill its buffer with requests on the given
93  /// commodity of composition c and the given preference. This must be called
94  /// at least once or the policy will do nothing. The policy can request on an
95  /// arbitrary number of commodities by calling Set multiple times. Re-calling
96  /// Set to modify the composition or preference of a commodity that has been
97  /// set previously is allowed.
98  /// @param commod the commodity name
99  /// @param c the composition to request for the given commodity
100  /// @param pref the preference value for the commodity
101  /// @{
102  MatlBuyPolicy& Set(std::string commod);
103  MatlBuyPolicy& Set(std::string commod, Composition::Ptr c);
104  MatlBuyPolicy& Set(std::string commod, Composition::Ptr c, double pref);
105  /// @}
106 
107  /// Registers this policy as a trader in the current simulation. This
108  /// function must be called for the policy to begin participating in resource
109  /// exchange. Init MUST be called prior to calling this function. Start is
110  /// idempotent.
111  void Start();
112 
113  /// Unregisters this policy as a trader in the current simulation. This
114  /// function need only be called if a policy is to be stopped *during* a
115  /// simulation (it is not required to be called explicitly at the end). Stop
116  /// is idempotent.
117  void Stop();
118 
119  /// the total amount requested
120  inline double TotalQty() const {
121  return std::min(throughput_,
122  fill_to_ * buf_->capacity() - buf_->quantity());
123  }
124 
125  /// whether trades will be denoted as exclusive or not
126  inline bool Excl() const { return quantize_ > 0; }
127 
128  /// the amount requested per each request
129  inline double ReqQty() const {
130  return Excl() ? quantize_ : TotalQty();
131  }
132 
133  /// the number of requests made per each commodity
134  inline int NReq() const {
135  return Excl() ? static_cast<int>(TotalQty() / quantize_) : 1;
136  }
137 
138  /// Returns corresponding commodities from which each material object
139  /// was received for the current time step. The data returned by this function
140  /// are ONLY valid during the Tock phase of a time step.
141  inline const std::map<Material::Ptr, std::string>& rsrc_commods() {
142  return rsrc_commods_;
143  };
144 
145  /// Trader Methods
146  /// @{
147  virtual std::set<RequestPortfolio<Material>::Ptr> GetMatlRequests();
148  virtual void AcceptMatlTrades(
149  const std::vector<std::pair<Trade<Material>, Material::Ptr> >& resps);
150  /// }@
151 
152  private:
153  struct CommodDetail {
154  Composition::Ptr comp;
155  double pref;
156  };
157 
158  /// requires buf_ already set
159  void set_fill_to(double x);
160  /// requires buf_ already set
161  void set_req_when_under(double x);
162  void set_quantize(double x);
163  void set_throughput(double x);
164 
165  ResBuf<Material>* buf_;
166  std::string name_;
167  double fill_to_, req_when_under_, quantize_, throughput_;
168  std::map<Material::Ptr, std::string> rsrc_commods_;
169  std::map<std::string, CommodDetail> commod_details_;
170 };
171 
172 } // namespace toolkit
173 } // namespace cyclus
174 
175 #endif
boost::shared_ptr< Composition > Ptr
Definition: composition.h:43
void Start()
Registers this policy as a trader in the current simulation.
bool Excl() const
whether trades will be denoted as exclusive or not
MatlBuyPolicy()
Creates an uninitialized policy.
boost::shared_ptr< Material > Ptr
Definition: material.h:75
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
double ReqQty() const
the amount requested per each request
MatlBuyPolicy & Init(Agent *manager, ResBuf< Material > *buf, std::string name)
Configures the policy to keep buf filled to a certain fraction of its capacity every time step...
virtual Agent * manager()
Definition: trader.h:28
virtual std::set< RequestPortfolio< Material >::Ptr > GetMatlRequests()
Trader Methods.
MatlBuyPolicy & Set(std::string commod)
Instructs the policy to fill its buffer with requests on the given commodity of composition c and the...
double TotalQty() const
the total amount requested
void Stop()
Unregisters this policy as a trader in the current simulation.
const std::map< Material::Ptr, std::string > & rsrc_commods()
Returns corresponding commodities from which each material object was received for the current time s...
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
int NReq() const
the number of requests made per each commodity
A Trade is a simple container that associates a request for a resource with a bid for that resource...
Definition: trade.h:16
virtual void AcceptMatlTrades(const std::vector< std::pair< Trade< Material >, Material::Ptr > > &resps)
default implementation for material trade acceptance
ResBuf is a helper class that provides semi-automated management of a collection of resources (e...
Definition: res_buf.h:62
MatlBuyPolicy performs semi-automatic inventory management of a material buffer by making requests an...