CYCLUS
Classes | Public Member Functions | List of all members
cyclus::toolkit::MatlBuyPolicy Class Reference

Detailed Description

MatlBuyPolicy performs semi-automatic inventory management of a material buffer by making requests and accepting materials in an attempt to fill the buffer fully every time step according to an (s, S) inventory policy (see [1]).

For simple behavior, policies virtually eliminate the need to write any code for resource exchange. Just assign a few policies to work with a few buffers and focus on writing the physics and other behvavior of your agent. Typical usage goes something like this:

class YourAgent : public cyclus::Facility {
public:
...
void EnterNotify() {
cyclus::Facility::EnterNotify(); // always do this first
policy_.Init(this, &inbuf_, "inbuf-label").Set(incommod, comp).Start();
}
...
private:
MatlBuyPolicy policy_;
ResBuf<Material> inbuf_;
...
}

The policy needs to be initialized with its owning agent and the material buffer that is is managing. It also needs to be activated by calling the Start function for it to begin participation in resource exchange. And don't forget to add some commodities to request by calling Set. All policy configuration should usually occur in the agent's EnterNotify member function.

[1] Zheng, Yu-Sheng. "A simple proof for optimality of (s, S) policies in infinite-horizon inventory systems." Journal of Applied Probability (1991): 802-810.

When a policy's managing agent is deallocated, you MUST either call the policy's Stop function or delete the policy. Otherwise SEGFAULT.

Definition at line 56 of file matl_buy_policy.h.

#include <matl_buy_policy.h>

Inheritance diagram for cyclus::toolkit::MatlBuyPolicy:
Inheritance graph
[legend]

Public Member Functions

bool Excl () const
 
 MatlBuyPolicy ()
 
int NReq () const
 
double ReqQty () const
 
const std::map< Material::Ptr, std::string > & rsrc_commods ()
 
void Start ()
 
void Stop ()
 
double TotalQty () const
 
virtual ~MatlBuyPolicy ()
 
MatlBuyPolicyInit (Agent *manager, ResBuf< Material > *buf, std::string name)
 
MatlBuyPolicyInit (Agent *manager, ResBuf< Material > *buf, std::string name, double throughput)
 
MatlBuyPolicyInit (Agent *manager, ResBuf< Material > *buf, std::string name, double fill_to, double req_when_under)
 
MatlBuyPolicyInit (Agent *manager, ResBuf< Material > *buf, std::string name, double throughput, double fill_to, double req_when_under, double quantize)
 
MatlBuyPolicySet (std::string commod)
 
MatlBuyPolicySet (std::string commod, Composition::Ptr c)
 
MatlBuyPolicySet (std::string commod, Composition::Ptr c, double pref)
 
- Public Member Functions inherited from cyclus::Trader
virtual void AcceptProductTrades (const std::vector< std::pair< Trade< Product >, Product::Ptr > > &responses)
 
virtual void AdjustMatlPrefs (PrefMap< Material >::type &prefs)
 
virtual void AdjustProductPrefs (PrefMap< Product >::type &prefs)
 
virtual std::set< BidPortfolio< Material >::Ptr > GetMatlBids (CommodMap< Material >::type &commod_requests)
 
virtual void GetMatlTrades (const std::vector< Trade< Material > > &trades, std::vector< std::pair< Trade< Material >, Material::Ptr > > &responses)
 
virtual std::set< BidPortfolio< Product >::Ptr > GetProductBids (CommodMap< Product >::type &commod_requests)
 
virtual std::set< RequestPortfolio< Product >::Ptr > GetProductRequests ()
 
virtual void GetProductTrades (const std::vector< Trade< Product > > &trades, std::vector< std::pair< Trade< Product >, Product::Ptr > > &responses)
 
virtual Agentmanager ()
 
 Trader (Agent *manager)
 
virtual std::set< RequestPortfolio< Material >::Ptr > GetMatlRequests ()
 
virtual void AcceptMatlTrades (const std::vector< std::pair< Trade< Material >, Material::Ptr > > &resps)
 

Additional Inherited Members

- Protected Attributes inherited from cyclus::Trader
Agentmanager_
 

Constructor & Destructor Documentation

◆ MatlBuyPolicy()

cyclus::toolkit::MatlBuyPolicy::MatlBuyPolicy ( )

Creates an uninitialized policy.

The Init function MUST be called before anything else is done with the policy.

Definition at line 16 of file matl_buy_policy.cc.

◆ ~MatlBuyPolicy()

cyclus::toolkit::MatlBuyPolicy::~MatlBuyPolicy ( )
virtual

Definition at line 27 of file matl_buy_policy.cc.

Member Function Documentation

◆ AcceptMatlTrades()

void cyclus::toolkit::MatlBuyPolicy::AcceptMatlTrades ( const std::vector< std::pair< Trade< Material >, Material::Ptr > > &  responses)
virtual

default implementation for material trade acceptance

Reimplemented from cyclus::Trader.

Definition at line 168 of file matl_buy_policy.cc.

◆ Excl()

bool cyclus::toolkit::MatlBuyPolicy::Excl ( ) const
inline

whether trades will be denoted as exclusive or not

Definition at line 126 of file matl_buy_policy.h.

◆ GetMatlRequests()

std::set< RequestPortfolio< Material >::Ptr > cyclus::toolkit::MatlBuyPolicy::GetMatlRequests ( )
virtual

Trader Methods.

Reimplemented from cyclus::Trader.

Definition at line 135 of file matl_buy_policy.cc.

◆ Init() [1/4]

MatlBuyPolicy & cyclus::toolkit::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.

Parameters
managerthe agent
bufthe resource buffer
namea unique name identifying this policy
throughputa constraining value for total transaction quantities in a single time step
fill_tothe amount or fraction of inventory to order when placing an order. This is equivalent to the S in an (s, S) inventory policy.
req_when_underplace an request when the buf's quantity is less than its capacity * fill_to (as a fraction). This is equivalent to the s in an (s, S) inventory policy.
quantizeIf quantize is greater than zero, the policy will make exclusive, integral quantize kg requests. Otherwise, single requests will be sent to fill the buffer's empty space.
Warning
, (s, S) policy values are ambiguous for buffers with a capacity in (0, 1]. However that is a rare case.

Definition at line 56 of file matl_buy_policy.cc.

◆ Init() [2/4]

MatlBuyPolicy & cyclus::toolkit::MatlBuyPolicy::Init ( Agent manager,
ResBuf< Material > *  buf,
std::string  name,
double  throughput 
)

Definition at line 64 of file matl_buy_policy.cc.

◆ Init() [3/4]

MatlBuyPolicy & cyclus::toolkit::MatlBuyPolicy::Init ( Agent manager,
ResBuf< Material > *  buf,
std::string  name,
double  fill_to,
double  req_when_under 
)

Definition at line 73 of file matl_buy_policy.cc.

◆ Init() [4/4]

MatlBuyPolicy & cyclus::toolkit::MatlBuyPolicy::Init ( Agent manager,
ResBuf< Material > *  buf,
std::string  name,
double  throughput,
double  fill_to,
double  req_when_under,
double  quantize 
)

Definition at line 84 of file matl_buy_policy.cc.

◆ NReq()

int cyclus::toolkit::MatlBuyPolicy::NReq ( ) const
inline

the number of requests made per each commodity

Definition at line 134 of file matl_buy_policy.h.

◆ ReqQty()

double cyclus::toolkit::MatlBuyPolicy::ReqQty ( ) const
inline

the amount requested per each request

Definition at line 129 of file matl_buy_policy.h.

◆ rsrc_commods()

const std::map<Material::Ptr, std::string>& cyclus::toolkit::MatlBuyPolicy::rsrc_commods ( )
inline

Returns corresponding commodities from which each material object was received for the current time step.

The data returned by this function are ONLY valid during the Tock phase of a time step.

Definition at line 141 of file matl_buy_policy.h.

◆ Set() [1/3]

MatlBuyPolicy & cyclus::toolkit::MatlBuyPolicy::Set ( std::string  commod)

Instructs the policy to fill its buffer with requests on the given commodity of composition c and the given preference.

This must be called at least once or the policy will do nothing. The policy can request on an arbitrary number of commodities by calling Set multiple times. Re-calling Set to modify the composition or preference of a commodity that has been set previously is allowed.

Parameters
commodthe commodity name
cthe composition to request for the given commodity
prefthe preference value for the commodity

Definition at line 98 of file matl_buy_policy.cc.

◆ Set() [2/3]

MatlBuyPolicy & cyclus::toolkit::MatlBuyPolicy::Set ( std::string  commod,
Composition::Ptr  c 
)

Definition at line 104 of file matl_buy_policy.cc.

◆ Set() [3/3]

MatlBuyPolicy & cyclus::toolkit::MatlBuyPolicy::Set ( std::string  commod,
Composition::Ptr  c,
double  pref 
)

Definition at line 108 of file matl_buy_policy.cc.

◆ Start()

void cyclus::toolkit::MatlBuyPolicy::Start ( )

Registers this policy as a trader in the current simulation.

This function must be called for the policy to begin participating in resource exchange. Init MUST be called prior to calling this function. Start is idempotent.

Definition at line 117 of file matl_buy_policy.cc.

◆ Stop()

void cyclus::toolkit::MatlBuyPolicy::Stop ( )

Unregisters this policy as a trader in the current simulation.

This function need only be called if a policy is to be stopped during a simulation (it is not required to be called explicitly at the end). Stop is idempotent.

Definition at line 126 of file matl_buy_policy.cc.

◆ TotalQty()

double cyclus::toolkit::MatlBuyPolicy::TotalQty ( ) const
inline

the total amount requested

Definition at line 120 of file matl_buy_policy.h.


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