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.

@warn 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 59 of file matl_buy_policy.h.

#include <matl_buy_policy.h>

Inheritance diagram for cyclus::toolkit::MatlBuyPolicy:

Public Member Functions
bool	dormant (int time)

bool	Excl () const

bool	MakeReq () const

	MatlBuyPolicy ()

bool	no_cycle_end_time ()

int	NReq (double amt) const

double	ReqQty (double amt) const

const std::map< Material::Ptr, std::string > &	rsrc_commods ()

void	Start ()

void	Stop ()

double	TotalAvailable () const

bool	use_cumulative_capacity ()

virtual	~MatlBuyPolicy ()


MatlBuyPolicy &	Init (Agent manager, ResBuf< Material > buf, std::string name, TotalInvTracker *buf_tracker)

MatlBuyPolicy &	Init (Agent manager, ResBuf< Material > buf, std::string name, TotalInvTracker *buf_tracker, double throughput, IntDistribution::Ptr active_dist=NULL, IntDistribution::Ptr dormant_dist=NULL, DoubleDistribution::Ptr size_dist=NULL)

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

MatlBuyPolicy &	Init (Agent manager, ResBuf< Material > buf, std::string name, TotalInvTracker *buf_tracker, double throughput, std::string inv_policy, double fill_behav, double req_at)

MatlBuyPolicy &	Init (Agent manager, ResBuf< Material > buf, std::string name, TotalInvTracker *buf_tracker, std::string inv_policy, double fill_behav, double req_at)

MatlBuyPolicy &	Init (Agent manager, ResBuf< Material > buf, std::string name, TotalInvTracker *buf_tracker, double throughput, double cumulative_cap, IntDistribution::Ptr)


MatlBuyPolicy &	Set (std::string commod)

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

MatlBuyPolicy &	Set (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 Agent *	manager ()

	Trader (Agent *manager)

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

virtual void	AcceptMatlTrades (const std::vector< std::pair< Trade< Material >, Material::Ptr > > &resps)

void	SetNextActiveTime ()

void	SetNextDormantTime ()

double	SampleRequestSize ()

void	CheckActiveDormantCumulativeTimes ()

Additional Inherited Members
Protected Attributes inherited from cyclus::Trader
Agent *	manager_

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 32 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 304 of file matl_buy_policy.cc.

◆ CheckActiveDormantCumulativeTimes()

void cyclus::toolkit::MatlBuyPolicy::CheckActiveDormantCumulativeTimes ( )

Definition at line 350 of file matl_buy_policy.cc.

◆ dormant()

bool cyclus::toolkit::MatlBuyPolicy::dormant ( int time )

inline

Definition at line 207 of file matl_buy_policy.h.

◆ Excl()

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

inline

whether trades will be denoted as exclusive or not

Definition at line 183 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 259 of file matl_buy_policy.cc.

◆ Init() [1/6]

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

Configures the policy to keep buf filled to a certain fraction of its capacity every time step.

Parameters

manager	the agent
buf	the resource buffer
name	a unique name identifying this policy
throughput	a constraining value for total transaction quantities in a single time step
inv_policy	the inventory policy to use. Options are "sS", "RQ". Each inventory policy options has two additional required parameters. An (s,S) inventory policy orders material only when the buffer is below the minimum value, s, and orders only enough to bring the buffer to the maximum value, S. An (s,S) policy allows partial orders. Set s as req_at and S as fill. An (R,Q) inventory policy requests material when the buffer is below the minimum value, R, and places an exclusive request for size Q. Set R as req_at and Q as fill.
req_at,the	inventory minimum (s, and R) for (s,S) and (R,Q),. If the buffer has less than or equal to value, new material will be requested based on the policy in place.
fill_behav,the	quantity govering the fill strategy for inventory policies. For (s,S), this is the maximum value, and material will be ordered up to this amount. For (R,Q), this is the quantity of material that will be ordered (exclusive).
cumulative_cap	the cumulative capacity of material to be received in one active cycle. A cumulative cap inventory policy allows for a cumulative capacity of material to be received in one active cycle. Once the cumulative capacity is recieved, the agent enters a dormant period. Also requires dormant distributions using dormant_dist.
quantize	If 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. The following features, if used, will set the policy to so that agents cycle through "on" phases, where the buf will attemp to be filled, and "off" or dormant phases, where no requests will be made regardless of capacity. The "on" and "off" phases are sampled and rounded to the nearest integer number of time steps from a truncated normal distribution from a mean, standard deviation, min, and max value. Note that the (s, S) policy is not currently compatible with active and Active and dormant buying perionds Active parameters:

Parameters

active_dist	an IntDistribution object that will be used to sample the number of time steps in the "on" phase. If not set, a fixed distribution with a value of 1 will be used.
dormant_dist	an IntDistribution object that will be used to sample the number of time steps in the "off" phase. If not set, a fixed distribution with a value of 0 will be used (no dormant, always on)
size_dist	a DoubleDistribution object that will be used to sample the size of the request as a fraction of the available capacity at the current time step. If not set, a fixed distribution with a value of 1.0 will be used. Note that active and dormant periods are note currently compatible with (s, S) inventory management

Definition at line 136 of file matl_buy_policy.cc.

◆ Init() [2/6]

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

◆ Init() [3/6]

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

Definition at line 163 of file matl_buy_policy.cc.

◆ Init() [4/6]

MatlBuyPolicy & cyclus::toolkit::MatlBuyPolicy::Init	(	Agent *	manager,
		ResBuf< Material > *	buf,
		std::string	name,
		TotalInvTracker *	buf_tracker,
		double	throughput,
		IntDistribution::Ptr	active_dist = NULL,
		IntDistribution::Ptr	dormant_dist = NULL,
		DoubleDistribution::Ptr	size_dist = NULL )

◆ Init() [5/6]

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

Definition at line 176 of file matl_buy_policy.cc.

◆ Init() [6/6]

MatlBuyPolicy & cyclus::toolkit::MatlBuyPolicy::Init	(	Agent *	manager,
		ResBuf< Material > *	buf,
		std::string	name,
		TotalInvTracker *	buf_tracker,
		std::string	inv_policy,
		double	fill_behav,
		double	req_at )

Definition at line 192 of file matl_buy_policy.cc.

◆ MakeReq()

bool cyclus::toolkit::MatlBuyPolicy::MakeReq ( ) const

inline

whether a request can be made

Definition at line 180 of file matl_buy_policy.h.

◆ no_cycle_end_time()

bool cyclus::toolkit::MatlBuyPolicy::no_cycle_end_time ( )

inline

Definition at line 203 of file matl_buy_policy.h.

◆ NReq()

int cyclus::toolkit::MatlBuyPolicy::NReq ( double amt ) const

inline

the number of requests made per each commodity

Definition at line 192 of file matl_buy_policy.h.

◆ ReqQty()

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

inline

the amount requested per each request

Definition at line 187 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 199 of file matl_buy_policy.h.

◆ SampleRequestSize()

double cyclus::toolkit::MatlBuyPolicy::SampleRequestSize ( )

Definition at line 346 of file matl_buy_policy.cc.

◆ 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

commod	the commodity name
c	the composition to request for the given commodity
pref	the preference value for the commodity

Definition at line 222 of file matl_buy_policy.cc.

◆ Set() [2/3]

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

Definition at line 228 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 232 of file matl_buy_policy.cc.

◆ SetNextActiveTime()

void cyclus::toolkit::MatlBuyPolicy::SetNextActiveTime ( )

}@

Definition at line 328 of file matl_buy_policy.cc.

◆ SetNextDormantTime()

void cyclus::toolkit::MatlBuyPolicy::SetNextDormantTime ( )

Definition at line 333 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 241 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 250 of file matl_buy_policy.cc.

◆ TotalAvailable()

double cyclus::toolkit::MatlBuyPolicy::TotalAvailable ( ) const

inline

the total amount available to request

Definition at line 172 of file matl_buy_policy.h.

◆ use_cumulative_capacity()

bool cyclus::toolkit::MatlBuyPolicy::use_cumulative_capacity ( )

inline

Definition at line 211 of file matl_buy_policy.h.

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

Detailed Description

Public Member Functions

Additional Inherited Members

Constructor & Destructor Documentation

◆ MatlBuyPolicy()

◆ ~MatlBuyPolicy()

Member Function Documentation

◆ AcceptMatlTrades()

◆ CheckActiveDormantCumulativeTimes()

◆ dormant()

◆ Excl()

◆ GetMatlRequests()

◆ Init() [1/6]

◆ Init() [2/6]

◆ Init() [3/6]

◆ Init() [4/6]

◆ Init() [5/6]

◆ Init() [6/6]

◆ MakeReq()

◆ no_cycle_end_time()

◆ NReq()

◆ ReqQty()

◆ rsrc_commods()

◆ SampleRequestSize()

◆ Set() [1/3]

◆ Set() [2/3]

◆ Set() [3/3]

◆ SetNextActiveTime()

◆ SetNextDormantTime()

◆ Start()

◆ Stop()

◆ TotalAvailable()

◆ use_cumulative_capacity()