CALVIN API

class calvin.calvin.CALVIN(linksfile, ic=None, log_name='calvin')

Bases: object

Initialize CALVIN model object.

Parameters:
  • linksfile – (string) CSV file containing network link information
  • ic – (dict) Initial storage conditions for surface reservoirs only used for annual optimization
  • log_name –

    A name for a logger - will be used to keep logs from different model runs separate in files. Defaults to “calvin”, which results in a log file in the current working directory named “calvin.log”. You can change this each time you instantiate the CALVIN class if you want to output separate logs for different runs. Otherwise, all results will be appended to the log file (not overwritten). If you run multiple copies of CALVIN simultaneously, make sure to change this, or you could get errors writing to the log file.

    Do not provide a full path to a log file here because this value is also used in a way that is not a file path. If being able to specify a full path is important for your workflow, please raise a GitHub issue. It could be supported, but there is no need at this moment.
Returns:

CALVIN model object
add_ag_region_sinks()

Hack to get rid of surplus water at no cost from agricultural regions. Called internally when model is initialized.

Returns:nothing, but modifies the model object
apply_ic(ic)

Set initial storage conditions.

Parameters:ic – (dict) initial storage values
Returns:nothing, but modifies the model object
create_pyomo_model(debug_mode=False, debug_cost=20000000.0)

Use link data to create Pyomo model (constraints and objective function) But do not solve yet.

Parameters:
  • debug_mode – (boolean) Whether to run in debug mode. Use when there may be infeasibilities in the network.
  • debug_cost – When in debug mode, assign this cost ($/AF) to flow on debug links. This should be an arbitrarily high number.
Returns:

nothing, but creates the model object (self.model)
eop_constraint_multiplier(x)

Set end-of-period storage constraints as a fraction of maximum available storage. Needed for limited foresight (annual) optimization.

Parameters:x – (float) fraction of maximum storage to set lower bound
Returns:nothing, but modifies the model object
fix_debug_flows(tol=1e-07)

Find infeasible constraints where debug flows occur. Fix them by either raising the UB, or lowering the LB.

Parameters:tol – (float) Tolerance to identify nonzero debug flows
Returns run_again:
 (boolean) whether debug mode needs to run again
Returns vol:(float) total volume of constraint changes also modifies the model object.
fix_hydropower_lbs()

Hack to fix lower bound constraints on piecewise hydropower links. Storage piecewise links > 0 should have 0.0 lower bound, and the k=0 pieces should always have lb = dead pool.

Returns:nothing, but modifies the model object
inflow_multiplier(x)

Multiply all network inflows by a constant.

Parameters:x – (float) value to multiply inflows
Returns:nothing, but modifies the model object
networkcheck()

Confirm constraint feasibility for the model object. (No inputs or outputs) :raises: ValueError when infeasibilities are identified.

no_gw_overdraft()

Impose constraints to prevent groundwater overdraft

(not currently implemented)

Remove debug links from model object.

Returns:dataframe of links, excluding debug links.
solve_pyomo_model(solver='glpk', nproc=1, debug_mode=False, maxiter=10)

Solve Pyomo model (must be called after create_pyomo_model)

Parameters:
  • solver – (string) solver name. glpk, cplex, cbc, gurobi.
  • nproc – (int) number of processors. 1=serial.
  • debug_mode – (boolean) Whether to run in debug mode. Use when there may be infeasibilities in the network.
  • maxiter – (int) maximum iterations for debug mode.
Returns:

nothing, but assigns results to self.model.solutions.
Raises:

RuntimeError, if problem is found to be infeasible.