jbae11 / d3ploy

A collection of Cyclus manager archetypes for demand driven deployment

d3ploy

A collection of Cyclus manager archetypes for demand driven deployment. It operates using global calls within a Cyclus simulation so that all agents within the simulation can communicate. The goal of this package is to provide three types of mathematical basis for predicting supply and demand of commodities within Cyclus; Non-optimizing (NO) deterministing optimization (DO), and Stochastic optimization (SO).

Dependencies

Cyclus: Fuel cycle simulation tool. Documentation

statsmodels: Python package for statistical analysis.Documentation

arch: Python package for conditional heteroskidasticity models.Documentation

Pmdarima: A python package for ARIMA/SARIMA methods. Documentation

timeseries_inst and supply_driven_deployment_inst

timeseries_inst

timeseries_inst is a Cyclus Institution archetype that performs demand-driven deployment of Cyclus agents.

The institution works by using the chosen method to predict supply and demand for given commodities. Each timestep the institution calculates a prediction on the supply and demand for the next time step. If the demand exceeds the supply it deploys facilities to ensure supply exceeds demand. Predictions are not performed if the method chosen by the institution is 'moving average'. In this instance the institution will schedule facilities for deployment only if there is a deficit in the current time step.

This institution is used for facilities that exist in the front end of the fuel cycle.

supply_driven_deployment_inst

supply_driven_deployment_inst is a Cyclus Institution archetype that performs supply-driven deployment of Cyclus agents.

The institution works by using the chosen method to predict supply and capacity for given commodities. Each timestep the institution calculates a prediction on the supply and capacity for the next time step. If the supply exceeds the capacity it deploys facilities to ensure capacity exceeds supply. Predictions are not performed if the method chosen by the institution is 'moving average'. In this instance the institution will schedule facilities for deployment only if there is a deficit in the current time step.

This institution is used for facilities that exist in the back end of the fuel cycle.

Required Inputs

• commodities: This is a list of strings defining the commodity to track, facility (depending on the institution used), the (initial) capacity of the facility, and the preference of the facility, given by format commodity_facility_capacity_preference. The preference can be given as an equation, using t as the dependent variable (e.g. (1.01)**t). The only difference between timeseries_inst and supply_driven_deployment_inst is this input. For timeseries_inst, the facility included should be the facility that supplies the commodity. For supply_driven_deployment_inst, the facility included should be the facility that supplies capacity for that commodity.
• driving_commod: The driving commodity for the institution.
• demand_eq: The demand equation for the driving commodity, using t as the dependent variable.
• calc_method: This is the method used to predict the supply and demand.

Prediction Methods

Prediction methods are categorized in three - Non-optimizing, deterministic-optimizing, and stochastic-optimizing.

Non-Optimizing Methods

There are three methods implemented for the NO models. Autoregressive moving average (ARMA), and autoregressive conditional heteroskedasticity (ARCH). There are four parameters users can define:

• steps: Number of timesteps forward to prdict supply and demand (default = 2)
• back_steps: Number of steps backwards from the current timestep to use for the prediction (default = 10)
• supply_std_dev = Standard deviation adjustment for supply (default = 0)
• demand_std_dev = Standard deviation adjustment for demand (default = 0)

MA (ma)

ARMA (arma)

The autoregressive moving average method takes a time series and uses an auto regressive term and a moving average term.

ARCH (arch)

The Autoregressive Conditional Heteroskedasticity (ARCH) method predicts the future value by using the observed values of returns or residuals.

Deterministic Optimization

There are three methods implemented for the DO models. Polynomial fit regression, simple exponential smoothing, and triple exponential smoothing (holt-winters). There are two parameters users can define:

• back_steps: Number of steps backwards from the current timestep to use for the prediction (default = 10)
• degree : degree of polynomial fit (default = 1)

Polynomial fit regression (poly)

The polynomial fit regression method fits a polynomial equation of degree k (degree) for the n (back_steps) previous values to predict the next value. A polynomial equation of degree 1 is a linear equation (y = ax + b) This method is suitable for values with a clear trend.

Exponential smoothing (exp_smoothing)

The exponential smoothing method takes the weighted average of past n (back_steps), in which more weight is given to the last observation. This method is suitable for values with no clear trend or pattern.

Triple exponential smoothing, Holt-Winters (holt_winters)

The triple smoothing method combines three smoothing equations - one for the level, one for trend, and one for the seasonal component - to predict the next value. This method is suitable for values with seasonality.

Fast Fourier Transform (fft)

(EXPERIMENTAL) The method builds a function that represents the data as a sumation of harmonics of different order. In the case of having a set of data that presents oscilations the user should set the degree to 2.

Stochastic Optimization

Currently a work in progress

Demand Fac

This facility is a test facility for D3ploy. It generates a random amount of supply and demand for commodities, and then reports these using the RecordTimeSeries functions inside of Cyclus.Thus providing a supply and demand to the institutions.

Amount of commodity demanded and supplied can be determined randomly through their minimum and maximum values. If for instance you'd like variability in the production rate of your supply you can set these minimum and maximum values to reflect that.

Required Inputs

• demand_commod: This is the commodity that the facility demands in order to operate.
• demand_rate_min: Minimum amount of the demanded commodity needed.
• demand_rate_max: Maximum amount of the demanded commodity needed.
• supply_commod: The commodity that the facility supplies.
• supply_rate_min: Minimum rate of production of the supplied commodity.
• supply_rate_max: Maximum rate of production of the supplied commodity.

Optional Inputs

• demand_ts: The amount of time steps between demanding material. For example a reactor may only demand material every 18 months.
• supply_ts: The amount of time steps between supplying material.