CALVIN API

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

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 – (string) Logger name; used as the log filename stem. Defaults to “calvin” → writes calvin.log in logdir (or cwd).

• logdir – (string) Directory to write the log file. Defaults to the directory containing linksfile.

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, cosvf_mode=False)

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.

• cosvf_mode – (boolean) When in COSVF mode, use debug links but preserve all network link costs.

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 (DBUGSNK) or lowering the LB (DBUGSRC).

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

Returns total_debug:

(float) total debug flow volume in this iteration also modifies the model object.

get_bound_adjustments()

Return a dataframe of links whose bounds were modified by fix_debug_flows, showing the initial and final lower/upper bounds and the net delta.

Returns:

DataFrame with columns i, j, k, lb_init, lb_final, lb_delta, ub_init, ub_final, ub_delta — only rows where at least one bound changed.

inflow_multiplier(x)

Multiply all network inflows by a constant.

Parameters:

x – (float) value to multiply inflows

Returns:

nothing, but modifies the model object

model_to_dataframe()

Converts the model to a pandas dataframe. Useful for computing objective values (costs) without having to postprocess.

Returns model_df:

(Pandas dataframe) Dataframe of upper_bound, cost, and flow (solution) values for each link

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

Remove debug links from model object.

Returns:

dataframe of links, excluding debug links.

solve_pyomo_model(solver='highs', 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.

calvin.calvin.setup_logger(log_name, savedir=None, console_level=20)

Create the logger

Parameters:

console_level – (int) logging level for the console handler (default INFO). Pass logging.WARNING in EA worker processes to suppress per-solve console noise while still writing full DEBUG output to the log file.