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

MatlBuyPolicy &	ResetBehavior ()

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

void	Start ()

void	Stop ()

double	TotalAvailable () const

MatlBuyPolicy &	Unset (std::string commod)

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 ()

void	RecordActiveDormantTime (int time, std::string type, int length)

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

◆ CheckActiveDormantCumulativeTimes()

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

Definition at line 390 of file matl_buy_policy.cc.

◆ dormant()

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

inline

Definition at line 217 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 193 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 278 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 149 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 176 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 189 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 205 of file matl_buy_policy.cc.

◆ MakeReq()

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

inline

whether a request can be made

Definition at line 190 of file matl_buy_policy.h.

◆ no_cycle_end_time()

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

inline

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

◆ RecordActiveDormantTime()

void cyclus::toolkit::MatlBuyPolicy::RecordActiveDormantTime	(	int	time,
		std::string	type,
		int	length )

Definition at line 403 of file matl_buy_policy.cc.

◆ ReqQty()

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

inline

the amount requested per each request

Definition at line 197 of file matl_buy_policy.h.

◆ ResetBehavior()

MatlBuyPolicy & cyclus::toolkit::MatlBuyPolicy::ResetBehavior ( )

Reset a material buy policy parameters that govern its behavior to the default state.

Preserve the Trader that manages the policy. The primary use case of this method is when there is a desire to change the behavior of a policy. This reset can be called prior to calling a new Init() to establish the new behavior.

Definition at line 37 of file matl_buy_policy.cc.

◆ 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 209 of file matl_buy_policy.h.

◆ SampleRequestSize()

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

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

◆ Set() [2/3]

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

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

◆ SetNextActiveTime()

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

}@

Definition at line 347 of file matl_buy_policy.cc.

◆ SetNextDormantTime()

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

Definition at line 360 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 260 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 269 of file matl_buy_policy.cc.

◆ TotalAvailable()

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

inline

the total amount available to request

Definition at line 182 of file matl_buy_policy.h.

◆ Unset()

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

Instructs the policy to stop requesting a speific commodity.

Definition at line 254 of file matl_buy_policy.cc.

◆ use_cumulative_capacity()

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

inline

Definition at line 221 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()

◆ RecordActiveDormantTime()

◆ ReqQty()

◆ ResetBehavior()

◆ rsrc_commods()

◆ SampleRequestSize()

◆ Set() [1/3]

◆ Set() [2/3]

◆ Set() [3/3]

◆ SetNextActiveTime()

◆ SetNextDormantTime()

◆ Start()

◆ Stop()

◆ TotalAvailable()

◆ Unset()

◆ use_cumulative_capacity()