Skip to content
Permalink
master
Switch branches/tags

Name already in use

A tag already exists with the provided branch name. Many Git commands accept both tag and branch names, so creating this branch may cause unexpected behavior. Are you sure you want to create this branch?
Go to file
 
 
Cannot retrieve contributors at this time
#ifndef CYCAMORE_SRC_LOOK_INST_H_
#define CYCAMORE_SRC_LOOK_INST_H_
#include <utility>
#include <set>
#include <map>
#include "cyclus.h"
#include "rwc_version.h"
namespace cycamore {
struct Short {
int start_period;
double shortfall;
};
/// The LookInst automatically deploys facilities in an attempt to efficiently
/// supply a user-specified demand curve. Although demand can be set to
/// anything by the user, electrical power/energy production is a common
/// usage. The user specifies one or more prototypes that can be deployed in
/// order to satisfy demand in a priority order. The LookInst makes deployment
/// decisions by running mini-simulations initialized by cloning the current
/// simulation state and running the mini-simulation ahead some lookahead
/// duration. The TimeSeries table specified by the user is checked to
/// determine any production shortfall compared to the user-specified demand
/// curve. Deployments are then shifted to lower priority prototypes as
/// necessary in order to reduce shortfall as much as possible.
///
/// Because the LookInst runs many internal simulations, it is slower than
/// running a simulation using similar deployments without the LookInst. The
/// size of this performance penalty varies depending on simulation details,
/// but a rough rule of thumb is ``10 * lookahead / deploy_period`` as a
/// multiplier on the simulation time when run with static deployments (e.g.
/// using the DeployInst). If a growth simulation runs in 20 seconds with the
/// DeployInst, then a 24 month lookahead with annual deployments will result
/// in an approximate 400 second simulation run time.
///
/// Due to limitations of how the LookInst operates, facilities that have
/// intermittent offline periods (e.g. reactors refueling) can cause
/// inefficient or undesired deployment decisions to occur. For example, if
/// reactors have a non-zero refueling period where they are not producing
/// electricity, then if their cycles are not staggered well, then periods with
/// more reactors offline refueling will cause the LookInst to shift many
/// deployments to lower priority prototypes unfruitfully in an attempt to meet
/// demand with little to no effect. This will result in undesired deployment
/// decisions in addition to a significant performance impact (i.e. slower
/// simulations). Ways to avoid this problem include:
///
/// - making sure online/offline cycles and the deploy period have a large
/// least common multiple for better staggering on average. For example,
/// make a reactor cycle (including refueling time) be something like 19 if
/// the deploy period is 12 months - if reactors are deployed annually, you
/// get 19 separate deployment periods before reactor cycles start to overlap.
///
/// - eliminate offline periods (with no production of e.g. power) effectively
/// increasing capacity factor to 100% and compensate by reducing production
/// capacity accordingly. For example, reduce reactor power capacity
/// to 900 MWe from 1000 MWe and reduce refueling time in the 20 month cycle
/// from 2 months to 0 months.
class LookInst : public cyclus::Institution {
#pragma cyclus note { \
"doc": \
"The LookInst automatically deploys facilities in an attempt to efficiently\n" \
" supply a user-specified demand curve. Although demand can be set to\n" \
" anything by the user, electrical power/energy production is a more common\n" \
" usage. The user specifies one or more prototypes that can be deployed in\n" \
" order to satisfy demand in a priority order. The LookInst makes deployment\n" \
" decisions by running mini-simulations initialized by cloning the current\n" \
" simulation state and running the mini-simulation ahead some lookahead\n" \
" duration. The TimeSeries table specified by the user is checked to\n" \
" determine any production shortfall compared to the user-specified demand\n" \
" curve. Deployments are then shifted to lower priority prototypes as\n" \
" necessary in order to reduce shortfall as much as possible.\n" \
"\n\n" \
"Because the LookInst runs many internal simulations, it is slower than\n" \
" running a simulation using similar deployments without the LookInst. The\n" \
" size of this performance penalty varies depending on simulation details,\n" \
" but a rough rule of thumb is ``10 * lookahead / deploy_period`` as a\n" \
" multiplier on the simulation time when run with static deployments (e.g.\n" \
" using the DeployInst). If a growth simulation runs in 20 seconds with the\n" \
" DeployInst, then a 24 month lookahead with annual deployments will result\n" \
" in an approximate 400 second simulation run time. \n" \
"\n\n" \
"Due to limitations of how the LookInst operates, facilities that have\n" \
" intermittent offline periods (e.g. reactors refueling) can cause\n" \
" inefficient or undesired deployment decisions to occur. For example, if\n" \
" reactors have a non-zero refueling period where they are not producing\n" \
" electricity, then if their cycles are not staggered well, then periods with\n" \
" more reactors offline refueling will cause the LookInst to shift many\n" \
" deployments to lower priority prototypes unfruitfully in an attempt to meet\n" \
" demand with little to no effect. This will result in undesired deployment\n" \
" decisions in addition to a significant performance impact (i.e. slower\n" \
" simulations). Ways to avoid this problem include:\n" \
"\n\n" \
"- making sure online/offline cycles and the deploy period have a large\n" \
" least common multiple for better staggering on average. For example,\n" \
" make a reactor cycle (including refueling time) be something like 19 if\n" \
" the deploy period is 12 months - if reactors are deployed annually, you\n" \
" get 19 separate deployments before reactor cycles start to overlap.\n" \
"\n\n" \
"- eliminate offline periods (with no production of e.g. power) effectively\n" \
" increasing capacity factor to 100% and compensate by reducting production\n" \
" capacity time unit accordingly. For example, reduce reactor power capacity\n" \
" to 900 MWe from 1000 MWe and reduce refueling time in the 20 month cycle\n" \
" from 2 months to 0 months.\n" \
"", \
}
public:
LookInst(cyclus::Context* ctx);
virtual ~LookInst();
virtual std::string version() {return RWC_VERSION;};
#pragma cyclus
virtual void EnterNotify();
virtual void Tock();
private:
// this is set to true when a sub-simulation is being run so that the
// sub simulation's LookInst doesn't waste CPU cycles computing deployments
// and also potentially causing an infinite recursion.
static bool am_ghost_;
// Runs a simulation from the current state through the lookahead window and
// returns the total capacity initially deployed at the start of the
// copied/cloned simulation moment (i.e. deploy_t-1) and each other deploy
// period time in the minisim. The map key is the simulation time. The
// returned value allows the calculation of how much additional capacity
// needs to be deployed.
std::map<int, double> RunSim(cyclus::SqliteBack* b, int deploy_t);
// lookto returns the end time of the current lookahead duration accounting
// for end-of-simulation where the lookahead window must be shrunk to not
// extend past the simulation's last time step.
int lookto(int deploy_t) {
return std::min(lookahead, context()->sim_info().duration - deploy_t);
}
bool UpdateNbuild(int deploy_t, Short fall);
// Computes the integrated shortfall of capacity-months by running a sub
// simulation forward from the given deployment time.
Short CalcShortfall(int deploy_t);
// Computes the number of new builds required to compensate for retirements
// and to satisfy demand growth for every deploy period within the lookahead
// window starting at the given deployment time. The result is stored
// inside the member variable nbuilds.
void CalcReqBuilds(int deploy_t);
int TimeOf(int period);
int PeriodOf(int t);
double WantCap(int t);
// Returns true if t is a deployment period time step.
bool OnDeploy(int t);
// Returns the capacity associated with the given set of builds - nbuild is
// an ordered list of build numbers of each prototype defined in
// proto_priority.
double CapOf(std::vector<int> nbuild);
// Returns the quantity of the demanded item that was produced at time t in
// the simulation data stored in db.
double CapAt(cyclus::SqliteDb& db, int t);
// NewCapBy returns the total capacity that was operating at time t in the
// simulation data stored in db. Since the sub simulations do not include
// entries from agents that were existing in the initial context clone, this
// only returns new capacity deployed following the start of the sub
// simulation in db and prior to t.
double NewCapBy(cyclus::SqliteDb& db, int t);
#pragma cyclus var { \
"doc": \
"A list of desired production levels at each deploy period that available prototypes will be deployed to meet." \
" The first deploy period starts on the time step *after* the LookInst is built." \
" The number of entries in the curve must be equal to or greater than" \
" the number of deploy periods in the simuation: ``floor((sim_dur - 2) / deploy_period) + 1``." \
"", \
}
std::vector<double> curve;
#pragma cyclus var { \
"doc": \
"The duration of time in between deployments made to meet the defined" \
" production curve." \
"", \
"units": "time steps", \
}
int deploy_period;
#pragma cyclus var { \
"doc": \
"The duration of time ahead of current time step for which under-capacity" \
" production is checked." \
" This should usually be near or larger than the deploy_period." \
"", \
"units": "time steps", \
}
int lookahead;
// name of timeseries table to get caps from (e.g. Power, etc.)
#pragma cyclus var { \
"default": "Power", \
}
std::string captable;
#pragma cyclus var { \
"doc": \
"This is an ordered list of prototypes that can/will be deployed to meet" \
" the defined production curve." \
" Prototypes earlier in this list are built preferentially before" \
" prototypes later in this list." \
" All prototypes that contribute capacity (i.e. add entries to the" \
" captable time series) must receive an entry in proto_priority - even if" \
" they are not available for building. Prototypes must be in order of" \
" availability - latest available to soonest available." \
"", \
}
std::vector<std::string> proto_priority;
#pragma cyclus var { \
"doc": \
"This is an ordered list of the capacity contribution of each prototype" \
" defined in proto_priority (same order as proto_priority)." \
" The capacity should generally include any capacity factor associated" \
" with the prototype's actual capacity. For example, if a reactor" \
" produces 1000 MWe when operating, but refuels for 2 months out of every" \
" 18, then the capacity value entered here should be ``1000 MWe / 9``." \
"", \
}
std::vector<double> proto_cap;
#pragma cyclus var { \
"default": [], \
"doc": \
"This is an ordered list of the time step on which each prototype becomes" \
" available for building (same order as proto_priority)." \
" If omitted, all prototypes are always available for building." \
" If a prototype is not ever available for building, use a time step" \
" after the end of the simulation. Note that because prototypes should" \
" be in order of availability - this list should be from highest time" \
" step to lowest." \
"", \
}
std::vector<int> proto_avail;
#pragma cyclus var { \
"default": [], \
"internal": True, \
}
std::vector<std::vector<int> > nbuilds;
// growths maps the deploy period to the amount of new capacity the lookinst
// must deploy in order for simulation total deployed capacity to match the
// capacity demand curve. This accounts for replacement of retiring capacity as
// well as capacity required to satisfy growth. This does NOT account for
// lower than 100% capacity factors on operating facilities.
#pragma cyclus var { \
"default": {}, \
"internal": True, \
}
std::map<int, double> growths;
// this is the recorder used in all of the sub simulations
cyclus::Recorder rec_;
};
} // namespace cycamore
#endif // CYCAMORE_SRC_LOOK_INST_H_