R6 Class for the Demand-Driven Transition Rate Program

A coupled linear program that derives per-transition flows from per-class area targets. It is assembled one constraint block at a time; every block has an add_ method of the same name, and lp_problem keeps the resulting rows tagged with that name so a program can be solved over a subset of its blocks. That is what makes the reachability precheck the same program as the solve, rather than a second implementation of it.

Units

The program is solved in shares of the landscape: shares and absolute areas are the same program up to a scalar, but the share version spans six fewer orders of magnitude. Everything the object returns is in cells, rehydrated against the number of cells lulc_data holds at the anchor period.

Periods

Following trans_rates_t, the flows of period p take the landscape from its state at p - 1 to its state at p. Area variables therefore exist at the anchor period – the last observed one – and at every extrapolated period, while flow variables exist at the extrapolated periods only.

Variables

All variables are non-negative. id_lulc identifies the class a class-level variable belongs to; id_lulc_anterior and id_lulc_posterior identify a transition-level one.

block	keys	meaning
`flow`	transition, period	cells moving along a transition
`area`	class, period	area of a class at a state
`rate_lower`, `rate_upper`	transition, period	rate-bound violation
`historic`	transition, period	distance from the historic outflow pattern
`shape`, `smoothness`	class, period	curvature violation
`target_over`, `target_under`	class	terminal fit either side of the target
`fairness`	none	worst per-class rate-bound violation

Constraint blocks

initial, conservation and closure are the mass balance; forbidden and rate_limits are the hard statements about what a transition may do; the rest carry slack variables and are paid for in the objective. blocks records which are enabled, which enter a solve and which enter the reachability precheck.

Installation

Solving needs lpSolve, which evoland only suggests: most of the package never solves a linear program. trans_rate_lp$new() fails with an actionable message if it is missing, so install it before constructing one – install.packages("lpSolve").

Super class

lp_problem -> trans_rate_lp

Active bindings

blocks: The constraint blocks, whether each is enabled, and which programs each takes part in.
scenario: Per class: the initial and target areas, the elicited shape and the objective weight.
transitions: Every ordered pair of classes with its rate bounds, whether it is viable, and whether the program forbids it.
steps: The extrapolated periods, the state each starts from, and its length.
reachability: Per class and period: the areas reachable under mass balance and hard historic rates, ignoring targets. Solved on demand and then cached.
areas: The solved class areas, in cells, per class and state.
flows: The solved transition flows, in cells.
rates: The solved flows as rates of their anterior class, which is what adjusted_trans_pot_v() and the allocators consume.
diagnostics: How far the solution had to depart from the target and from observed history. These are results, not debug output: a solver that does not report how far outside history it went is actively misleading.

Methods

Public methods

trans_rate_lp$new()
trans_rate_lp$add_all()
trans_rate_lp$add_initial()
trans_rate_lp$add_conservation()
trans_rate_lp$add_closure()
trans_rate_lp$add_forbidden()
trans_rate_lp$add_rate_limits()
trans_rate_lp$add_rate_bounds()
trans_rate_lp$add_historic()
trans_rate_lp$add_target()
trans_rate_lp$add_monotonicity()
trans_rate_lp$add_shape()
trans_rate_lp$add_smoothness()
trans_rate_lp$add_fairness()
trans_rate_lp$solve()
trans_rate_lp$print()
trans_rate_lp$trans_rates_t()
trans_rate_lp$clone()

Inherited methods

lp_problem$add_constraints()

`trans_rate_lp$new()`

Set up the program from an observed landscape and a scenario demand. Constraint blocks are added immediately, so the object is ready to solve. Requires the suggested lpSolve package to be installed.

Usage

trans_rate_lp$new(
  lulc_data,
  bounds,
  periods,
  targets = NULL,
  shapes = NULL,
  lambda_bounds = 0.1,
  mu_shape = 15,
  mu_smooth = 1,
  mu_target = 1000,
  mu_historic = 0,
  margin = 0.01,
  terminal_band = NA,
  shape_strictness = 0,
  monotone = TRUE,
  fairness = TRUE,
  forbid_non_viable = TRUE,
  max_reachability_ratio = 10
)

Arguments

lulc_data: A lulc_data_t for a single id_run. The areas of its last observed period are the initial state.
bounds: Per-transition rate bounds, see trans_rate_bounds().
periods: A periods_t. Its extrapolated periods are the steps to solve for, and their lengths set the time scale of the trajectory-shape constraints.
targets: A data.table with id_lulc and either area (cells on the same grid as lulc_data) or share (of the landscape, rehydrated against it). Without targets the object can only answer reachability.
shapes: A data.table with id_lulc and shape, one of "instant growth", "delayed growth", "constant change", "instant decline", "delayed decline". Note that a straight line satisfies every one of these one-sided curvature constraints, so shapes only bind when shape_strictness > 0.
lambda_bounds: Penalty weight on rate-bound violation.
mu_shape: Penalty weight on trajectory-shape violation.
mu_smooth: Penalty weight on the second difference of the trajectory; a tie-breaker among otherwise equivalent trajectories.
mu_target: Penalty weight on the L1 distance between the solved terminal area and the target. Without it, a hard terminal band is treated as free real estate and every class parks on a band edge.
mu_historic: Penalty weight on the L1 distance between flows and the historic outflow pattern (ref_rate). Zero by default; raising it keeps flows near the observed pattern where the target does not force otherwise.
margin: Slack around the rate bounds before a violation is penalised.
terminal_band: Relative half-width of a hard band around the terminal target, or NA (the default) to rely on mu_target alone. A hard band and forbid_non_viable together turn an out-of-reach target into an infeasible program rather than a near miss: on the SSP-CH demand that combination is infeasible for three of five scenarios, while the L1 fit lands as close as the viable transitions allow and reports the shortfall.
shape_strictness: Minimum curvature a shaped trajectory must exhibit, as a fraction of the class's mean per-step change.
monotone: Whether to hard-constrain each class to move monotonically in the direction of sign(target - init).
fairness: Minimax bound on the worst per-class rate-bound violation. TRUE uses lambda_bounds as its weight; a number sets the weight explicitly.
forbid_non_viable: Whether to hard-zero flows on transitions that trans_meta_t marks as non-viable. Such flows have no trans_pot_t rows and would be silently dropped at allocation time, so the trajectory would not materialise.
max_reachability_ratio: Refuse to solve if a target asks for more than this multiple of the historically achievable change. Everything below the threshold is reported, not gated.

Returns

A new trans_rate_lp object

`trans_rate_lp$add_all()`

Add every enabled constraint block, by calling the add_ method of the same name.