User-Defined Constraints — Syntax Reference

Range constraints

Range constraints bound an expression from both sides:

100 <= generator('G1').generation <= 500

This creates a single LP row with both lower and upper bounds.

Element references

Elements are referenced by type and identifier (name or UID):

generator('TORO').generation    -- by name
generator('uid:23').generation  -- by UID

Variable Scaling

Some LP variables are internally scaled to improve solver numerical conditioning. User constraints are written in physical units; the constraint resolver automatically applies the appropriate scale factor so that the LP constraint is dimensionally correct.

For example, reservoir("R1").volume >= 5000 (in dam³) is automatically translated to the LP constraint energy_scale × volume_LP ≥ 5000, accounting for the fact that the LP variable stores volume_physical / energy_scale.

Syntax

sum( element_type ( id_list ) . attribute )

Where id_list is one of:

• Explicit list: ‘'G1’, 'G2', 'G3'or1, 2, 3or mixed
• **All elements**:all`

Examples

# Sum generation over specific generators (by name)
sum(generator('G1', 'G2', 'G3').generation) <= 500

# Sum generation over specific generators (by UID)
sum(generator(1, 2, 3).generation) <= 500

# Mixed name and UID references
sum(generator('G1', 2, 'uid:3').generation) <= 500

# Sum over ALL generators in the system
sum(generator(all).generation) <= 1000

# Sum with a coefficient
0.5 * sum(demand('D1', 'D2').load) <= 200

# Combined: sum + individual elements
sum(generator('G1', 'G2').generation) + demand('D1').load <= 1000

# Balance constraint: total generation minus total demand
sum(generator(all).generation) - sum(demand(all).load) = 0

AMPL comparison

Dimension names

Index set forms

Syntax variants

Both in and = are accepted:

for(stage in {1,2,3})     -- using 'in'
for(stage = 1)            -- using '=' (single value)

Unspecified dimensions default to all:

for(block in 1..24)       -- all scenarios, all stages, blocks 1-24

Example 1 — Simple generation cap

Limit generator G1 to 100 MW:

{
  "uid": 1,
  "name": "g1_cap",
  "expression": "generator('G1').generation <= 100"
}

Example 2 — Joint generation limit

The sum of two generators must not exceed 300 MW:

{
  "uid": 2,
  "name": "gen_pair_limit",
  "expression": "generator('TORO').generation + generator('uid:23').generation <= 300, for(stage in {4,5,6}, block in 1..30)"
}

Example 3 — Minimum generation requirement

Generator G1 must produce at least 50 MW:

{
  "uid": 3,
  "name": "min_gen",
  "expression": "generator('G1').generation >= 50"
}

Example 4 — Line flow limit

Restrict flow on line L1_2 to 200 MW:

{
  "uid": 4,
  "name": "flow_limit",
  "expression": "line('L1_2').flow <= 200"
}

Example 5 — Generation-load balance

Generator G1 output must equal demand D1 load:

{
  "uid": 5,
  "name": "gen_demand_balance",
  "expression": "generator('G1').generation = demand('D1').load"
}

Example 6 — Range constraint

Generator output must be between 50 and 250 MW:

{
  "uid": 6,
  "name": "gen_range",
  "expression": "50 <= generator('G1').generation <= 250"
}

Example 7 — Weighted sum with coefficients

Partial contributions from two generators:

{
  "uid": 7,
  "name": "weighted_cap",
  "expression": "0.8 * generator('G1').generation + 0.5 * generator('G2').generation <= 200"
}

Example 8 — Cross-element CHP coupling

Model combined heat-and-power relationship (generation proportional to load):

{
  "uid": 8,
  "name": "chp_coupling",
  "expression": "generator('CHP').generation - 1.5 * demand('HeatLoad').load = 0"
}

Example 9 — Battery energy limit during peak hours

Limit battery state of energy during peak blocks:

{
  "uid": 9,
  "name": "bess_peak_limit",
  "expression": "battery('BESS1').energy <= 400, for(block in {18, 19, 20, 21})"
}

Example 10 — Scenario-specific constraint

Different limit in scenarios 1 and 2 only:

{
  "uid": 10,
  "name": "scenario_limit",
  "expression": "generator('G1').generation <= 150, for(scenario in {1, 2})"
}

Example 11 — Inactive constraint (disabled)

A constraint that is defined but not active:

{
  "uid": 11,
  "name": "maintenance_limit",
  "active": false,
  "expression": "generator('G1').generation <= 10"
}

Example 12 — Zero unserved energy requirement

Force no load curtailment on demand D1:

{
  "uid": 12,
  "name": "no_curtailment",
  "expression": "demand('D1').fail = 0"
}

Example 13 — Generator referenced by numeric UID

Use the bare integer syntax instead of ‘'uid:3’`:

{
  "uid": 13,
  "name": "gen_uid_limit",
  "expression": "generator(3).generation <= 200"
}

Example 14 — Sum over all generators (budget constraint)

Limit total system generation using sum():

{
  "uid": 14,
  "name": "total_gen_cap",
  "expression": "sum(generator(all).generation) <= 1000"
}

Example 15 — Sum over specific generators

Constrain a subset of generators:

{
  "uid": 15,
  "name": "thermal_limit",
  "expression": "sum(generator('G1', 'G2', 'G3').generation) <= 500, for(block in 1..12)"
}

Example 16 — Sum with coefficient (weighted budget)

Weighted sum of demand served:

{
  "uid": 16,
  "name": "weighted_demand",
  "expression": "0.5 * sum(demand('D1', 'D2').load) <= 200"
}

Example 17 — Balance: total generation equals total demand

System-wide power balance using two sum() terms:

{
  "uid": 17,
  "name": "system_balance",
  "expression": "sum(generator(all).generation) - sum(demand(all).load) = 0"
}

Example 18 — Reservoir volume constraint

Limit reservoir volume during dry season:

{
  "uid": 18,
  "name": "reservoir_min_vol",
  "expression": "reservoir('RES1').volume >= 1000, for(stage in {3, 4})"
}

Example 19 — Converter charge/discharge limit

Limit total converter throughput:

{
  "uid": 19,
  "name": "converter_limit",
  "expression": "converter('CV1').charge + converter('CV1').discharge <= 100"
}

Example 20 — Expression with comments

Use # or // for inline documentation (useful in external files):

{
  "uid": 20,
  "name": "documented_limit",
  "expression": "generator('G1').generation + generator('G2').generation <= 300 # peak capacity"
}

Example 21 — Reserve provision limit

Limit up-reserve provision of a specific provider:

{
  "uid": 21,
  "name": "up_reserve_limit",
  "expression": "reserve_provision('RP1').up <= 50"
}

Example 22 — Reserve zone total up-reserve

Constrain total up-reserve in a zone across all provisions:

{
  "uid": 22,
  "name": "zone_up_reserve_min",
  "expression": "reserve_zone('RZ1').up >= 100"
}

JSON format

{
  "system": {
    "bus_array": [...],
    "user_constraint_file": "constraints.json"
  }
}

External JSON file (constraints.json):

[
  {
    "uid": 1,
    "name": "gen_limit",
    "expression": "generator('G1').generation <= 100"
  },
  {
    "uid": 2,
    "name": "flow_limit",
    "expression": "line('L1').flow <= 200"
  }
]

PAMPL format

PAMPL (pseudo-AMPL) files provide a more readable syntax with named constraints, parameters, and comments:

# System constraints
param pct_elec = 35;
param seasonal[month] = [0,0,0,100,100,100,100,100,100,100,0,0];

constraint gen_limit "Combined generation limit":
  generator('G1').generation + generator('G2').generation <= 300;

constraint seasonal_limit:
  generator('G1').generation <= pct_elec * seasonal[month];

PAMPL files are loaded automatically when referenced:

{
  "system": {
    "user_constraint_file": "constraints.pampl"
  }
}

Multiple external files

Use user_constraint_files (plural, array) to load multiple files independently. Each file is parsed with auto-incremented UIDs to avoid collisions:

{
  "system": {
    "user_constraint_files": [
      "laja_agreement.pampl",
      "maule_agreement.pampl"
    ]
  }
}

This keeps each constraint set self-contained and avoids combining files. Both user_constraint_file (singular) and user_constraint_files (plural) can coexist — all sources are accumulated.

Combining inline and external

Both user_constraint_array and external files can be used simultaneously. Constraints from all sources are accumulated:

{
  "system": {
    "user_constraint_array": [
      {"uid": 1, "name": "inline_limit", "expression": "..."}
    ],
    "user_constraint_files": ["more_constraints.pampl"]
  }
}

Multi-file merge

When loading from multiple JSON files (the standard gtopt pattern), constraints from all files are accumulated via System::merge():

gtopt base.json overrides.json

AMPL equivalents

# ── gtopt: simple capacity constraint ──
# generator('G1').generation <= 100
# AMPL:
subject to g1_cap:
  generation["G1"] <= 100;

# ── gtopt: sum over element group ──
# sum(generator('G1','G2','G3').generation) <= 500, for(block in 1..12)
# AMPL:
subject to thermal_limit {b in 1..12}:
  sum{g in {"G1","G2","G3"}} generation[g,b] <= 500;

# ── gtopt: budget constraint (sum over all) ──
# sum(generator(all).generation) <= 1000
# AMPL:
subject to budget_constraint:
  sum{g in GENERATORS} generation[g] <= 1000;

# ── gtopt: cross-element balance ──
# sum(generator(all).generation) - sum(demand(all).load) = 0
# AMPL:
subject to balance:
  sum{g in GENERATORS} generation[g] - sum{d in DEMANDS} load[d] = 0;

# ── gtopt: weighted sum with domain ──
# 0.8 * generator('G1').generation + 0.5 * generator('G2').generation <= 200,
#     for(stage in {4,5,6}, block in 1..30)
# AMPL:
subject to weighted_cap {s in STAGES, b in BLOCKS: s in {4,5,6} and b >= 1 and b <= 30}:
  0.8 * generation["G1",s,b] + 0.5 * generation["G2",s,b] <= 200;

Key differences from AMPL

Design philosophy

The gtopt constraint language is intentionally narrower than AMPL:

• No set definitions needed: Element sets are implicit from the system model. sum(generator(all).generation) automatically sums over all generators in the system, without requiring a set GENERATORS; declaration.
• Element-centric: Variables are accessed via element references (‘generator('G1’).generation) rather than indexed arrays (generation["G1",s,b]`). This is more natural for power system engineers.
• JSON-native: Constraints live in JSON files alongside the rest of the case definition, enabling programmatic generation from scripts and GUIs.