Model definition schema¶

All options available to configure a Calliope model.

parameters (object): Calliope model arbitrary parameter definitions. Cannot contain additional properties.
- bigM: BigM is a large value used to define certain optimisation problems. See https://en.wikipedia.org/wiki/Big_M_method for more information. This value should be larger than the largest values that any decision variables can take, but should not be too large (i.e., do not set it greater than 3 orders of magnitude above the numeric range of the model). If too large, numerical problems may arise in the optimisation. Default: 1000000000.0.
  - One of
    - number
    - object: Cannot contain additional properties.
      - data (number)
- objective_cost_weights: Weightings for cost classes to apply in the objective function. Refer to #/$defs/TechCostNullNumber. Default: 1.
- ^[^_^\d][\w]*$
  - One of
    - : Refer to #/$defs/unIndexedParamVal.
    - : Refer to #/$defs/IndexedParam.
techs (object): Calliope model technology definitions. Cannot contain additional properties.
- ^[^_^\d][\w]*$ (object): A named technology. Can contain unevaluated properties.
  - All of
    - - One of
        
        base_tech: Must be: "conversion".
        
        base_tech: Must be: "demand".
        
        base_tech: Must be: "storage".
        
        base_tech: Must be: "supply".
        
        base_tech: Must be: "transmission".
        
        from (string): The resulting link technology will have flow_out == import and flow_in == export at this node.
        
        to (string): The resulting link technology will have flow_out == import and flow_in == export at this node.
  - Unevaluated properties
    - One of
      - : Refer to #/$defs/unIndexedParamVal.
      - object: Indexed tech-level parameter with any dtype. Cannot contain additional properties.
        
        data: Refer to #/$defs/IndexedParamData.
        
        index: Refer to #/$defs/IndexedParamIndex.
        
        dims: Refer to #/$defs/TechDims.
  - active: Refer to #/$defs/ActiveDef.
  - base_tech (string): Should be the name of one of the abstract base classes, from which some initial parameter defaults will be derived and with which certain base math will be triggered. Must be one of: ["demand", "supply", "conversion", "storage", "transmission"].
  - color (['null', 'string']): Color that can be used when plotting results. Default: NaN.
  - carrier_in: Carrier(s) consumed by this technology. Only transmission, conversion, storage, and demand technologies can define this parameter.
    - One of
      - string
      - array: Length must be at least 2.
        
        Items (string)
  - carrier_out: Carrier(s) produced by this technology. Only transmission, conversion, storage, and supply technologies can define this parameter.
    - One of
      - string
      - array: Length must be at least 2.
        
        Items (string)
  - carrier_export: Carrier(s) produced by this technology that can be exported out of the system boundaries without having to go to a pre-defined sink (i.e., via a demand technology). Must be a subset of carrier_out.
    - One of
      - string
      - array: Length must be at least 2.
  - name (['null', 'string']): Long name of technology, which can be used in post-processing (e.g., plotting). Default: NaN.
  - cap_method (string): One of 'continuous' (LP model) or 'integer' (integer/binary unit capacity). Must be one of: ["continuous", "integer"]. Default: "continuous".
  - integer_dispatch (boolean): When true, will limit per-timestep out/inflows relative to the number of units of a technology that are in operation. Requires cap_method=integer. Default: false.
  - include_storage (boolean): When true, math will be triggered to allow discontinuous carrier inflow and outflows across timesteps. Default: false.
  - force_async_flow (boolean): If True, non-zero flow_out and flow_in cannot both occur in the same timestep. Default: false.
  - flow_cap_per_storage_cap_min: ratio of minimum charge/discharge (kW) for a given storage capacity (kWh). Refer to #/$defs/TechParamNullNumber. Default: 0.
  - flow_cap_per_storage_cap_max: ratio of maximum charge/discharge (kW) for a given storage capacity (kWh). Refer to #/$defs/TechParamNullNumber. Default: Infinity.
  - flow_cap: Sets flow_cap to a parameter in operate mode. NOTE: this parameter cannot be used in plan mode as it clashes with the decision variable of the same name. Refer to #/$defs/TechParamNullNumber. Default: Infinity.
  - flow_cap_max: Limits flow_cap to a maximum. Refer to #/$defs/TechParamNullNumber. Default: Infinity.
  - flow_cap_max_systemwide: Limits the sum of flow_cap over all nodes in the model to a maximum. If cap_method=integer, this will be scaled by the number of integer units of a technology purchased. Refer to #/$defs/TechParamNullNumber. Default: Infinity.
  - flow_cap_min: This acts as lower limit (lower bound) for flow_cap. If cap_method = integer, this will be scaled by the number of integer units of a technology purchased.

Note

If cap_method = continuous (which is set by default), then setting flow_cap_min to any value greater than 0 forces the model to always respect that limit, which in turn forces investment into the technology. Use this to enforce given investment plans, or to account for existing technologies that cannot be decommissioned.
An example: If cap_method = continuous and flow_cap_min = 100, then flow_cap has to be at least 100. This means that going to 0 is not possible, unless you switch to cap_method = integer (see cap_method). Refer to #/$defs/TechParamNullNumber. Default: 0.

- **`flow_cap_min_systemwide`**: Limits the sum of `flow_cap` over all nodes in the model to a minimum. NOTE: this will _force_ the sum of `flow_cap` to a minimum value unless `cap_method` is set to `integer`. Refer to *[#/$defs/TechParamNullNumber](#%24defs/TechParamNullNumber)*. Default: `0`.

- **`flow_out_min_relative`**: Set to a value between 0 and 1 to force minimum `flow_out` as a fraction of the technology rated capacity. If non-zero and `cap_method` is `continuous`, this will force the technology to operate above its minimum value at every timestep. Refer to *[#/$defs/TechParamNullNumber](#%24defs/TechParamNullNumber)*. Default: `0`.

- **`flow_cap_per_unit`**: Set the capacity of each integer unit of a technology purchased, if `cap_method` is `integer`. Refer to *[#/$defs/TechParamNullNumber](#%24defs/TechParamNullNumber)*. Default: `NaN`.

- **`flow_in_eff`**: Conversion efficiency from `source`/`flow_in` (tech dependent) into the technology. Set as value between 1 (no loss) and 0 (all lost). Refer to *[#/$defs/TechParamNullNumber](#%24defs/TechParamNullNumber)*. Default: `1.0`.

- **`flow_out_eff`**: Conversion efficiency from the technology to `sink`/`flow_out` (tech dependent). Set as value between 1 (no loss) and 0 (all lost). Refer to *[#/$defs/TechParamNullNumber](#%24defs/TechParamNullNumber)*. Default: `1.0`.

- **`flow_out_parasitic_eff`**: Additional losses as flow gets transferred from the plant to the carrier, e.g. due to plant parasitic consumption. Set as value between 1 (no loss) and 0 (all lost). Refer to *[#/$defs/TechParamNullNumber](#%24defs/TechParamNullNumber)*. Default: `1.0`.

- **`flow_ramping`**: limit maximum outflow / inflow / outflow - inflow (technology base class dependent) to a fraction of maximum capacity, which increases by that fraction at each timestep. Refer to *[#/$defs/TechParamNullNumber](#%24defs/TechParamNullNumber)*. Default: `1.0`.

- **`export_max`**: If `carrier_export` is defined, limit the allowed export of produced carrier for a technology. Refer to *[#/$defs/TechParamNullNumber](#%24defs/TechParamNullNumber)*. Default: `Infinity`.

- **`lifetime`** *(['null', 'number'])*: Must be defined if fixed capital costs are defined. A reasonable value for many technologies is around 20-25 years. Default: `Infinity`.

- **`area_use`**: Sets `area_use` to a parameter in operate mode. NOTE: this parameter cannot be used in `plan` mode as it clashes with the decision variable of the same name. Refer to *[#/$defs/TechParamNullNumber](#%24defs/TechParamNullNumber)*. Default: `Infinity`.

- **`area_use_max`**: If set to a finite value, limits the upper bound of the `area_use` decision variable to this value. Refer to *[#/$defs/TechParamNullNumber](#%24defs/TechParamNullNumber)*. Default: `Infinity`.

- **`area_use_min`**: Limits the lower bound of the `area_use` decision variable to this value. Refer to *[#/$defs/TechParamNullNumber](#%24defs/TechParamNullNumber)*. Default: `0`.

- **`area_use_per_flow_cap`**: If set, forces `area_use` to follow `flow_cap` with the given numerical ratio (e.g. setting to 1.5 means that `area_use == 1.5 * flow_cap`). Refer to *[#/$defs/TechParamNullNumber](#%24defs/TechParamNullNumber)*. Default: `NaN`.

- **`storage_cap`**: Sets `storage_cap` to a parameter in operate mode. NOTE: this parameter cannot be used in `plan` mode as it clashes with the decision variable of the same name. Refer to *[#/$defs/TechParamNullNumber](#%24defs/TechParamNullNumber)*. Default: `Infinity`.

- **`storage_cap_max`**: Limit upper bound of `storage_cap` decision variable. Refer to *[#/$defs/TechParamNullNumber](#%24defs/TechParamNullNumber)*. Default: `Infinity`.

- **`storage_cap_min`**: Limit lower bound of `storage_cap` decision variable. Refer to *[#/$defs/TechParamNullNumber](#%24defs/TechParamNullNumber)*. Default: `0`.

- **`storage_cap_per_unit`**: Set the storage capacity of each integer unit of a technology purchased. Refer to *[#/$defs/TechParamNullNumber](#%24defs/TechParamNullNumber)*. Default: `NaN`.

- **`storage_discharge_depth`**: Defines the minimum level of storage state of charge, as a fraction of total storage capacity. Refer to *[#/$defs/TechParamNullNumber](#%24defs/TechParamNullNumber)*. Default: `0`.

- **`storage_initial`**: Set stored flow in device at the first timestep, as a fraction of total storage capacity. Refer to *[#/$defs/TechParamNullNumber](#%24defs/TechParamNullNumber)*. Default: `0`.

- **`storage_loss`**: Rate of storage loss per hour, used to calculate lost stored flow as `(1 - storage_loss)^hours_per_timestep`. Refer to *[#/$defs/TechParamNullNumber](#%24defs/TechParamNullNumber)*. Default: `0`.

- **`cyclic_storage`** *(boolean)*: If true, link storage levels in the last model timestep with the first model timestep. `inter_cluster_storage` custom math must be included if using time clustering and setting this to `true`. This must be set to `false` if using `operate` mode.

Default: true.

    - **`purchased_units_min_systemwide`**: sets the lower bound of the sum across all nodes of the decision variable `units` for a particular technology. Refer to *[#/$defs/TechParamNullNumber](#%24defs/TechParamNullNumber)*. Default: `0`.

    - **`purchased_units_max_systemwide`**: sets the upper bound of the sum across all nodes of the decision variable `units` for a particular technology. Refer to *[#/$defs/TechParamNullNumber](#%24defs/TechParamNullNumber)*. Default: `Infinity`.

    - **`purchased_units`**: Sets `purchased_units` to a parameter in operate mode. NOTE: this parameter cannot be used in `plan` mode as it clashes with the decision variable of the same name. Refer to *[#/$defs/TechParamNullNumber](#%24defs/TechParamNullNumber)*. Default: `Infinity`.

    - **`purchased_units_min`**: Limits the lower bound of units purchased if `cap_method` is `integer`. Refer to *[#/$defs/TechParamNullNumber](#%24defs/TechParamNullNumber)*. Default: `0`.

    - **`purchased_units_max`**: Limits the upper bound of units purchased if `cap_method` is `integer`. If set to `1`, will effectively set the `purchased_units` to a binary decision variable. Refer to *[#/$defs/TechParamNullNumber](#%24defs/TechParamNullNumber)*. Default: `Infinity`.

    - **`sink_unit`** *(string)*: Sets the unit of `Sink` to either `absolute` (unit: `energy`), `per_area` (unit: `energy/area`), or `per_cap` (unit: `energy/power`). `per_area` uses the `area_use` decision variable to scale the sink while `per_cap` uses the `flow_cap` decision variable. Must be one of: `["absolute", "per_area", "per_cap"]`. Default: `"absolute"`.

    - **`sink_use_min`**: Minimum sink use to remove a carrier from the system (e.g., electricity demand, transport distance). Unit dictated by `sink_unit`. Refer to *[#/$defs/TechParamNullNumber](#%24defs/TechParamNullNumber)*. Default: `0`.

    - **`sink_use_max`**: Maximum sink use to remove a carrier from the system (e.g., electricity demand, transport distance). Unit dictated by `sink_unit`. Refer to *[#/$defs/TechParamNullNumber](#%24defs/TechParamNullNumber)*. Default: `Infinity`.

    - **`sink_use_equals`**: Required amount of carrier removal from the system (e.g., electricity demand, transport distance). Unit dictated by `sink_unit`. Refer to *[#/$defs/TechParamNullNumber](#%24defs/TechParamNullNumber)*. Default: `NaN`.

    - **`source_unit`** *(string)*: Sets the unit of `Source` to either `absolute` (unit: `energy`), `per_area` (unit: `energy/area`), or `per_cap` (unit: `energy/power`). `per_area` uses the `area_use` decision variable to scale the source while `per_cap` uses the `flow_cap` decision variable. Must be one of: `["absolute", "per_area", "per_cap"]`. Default: `"absolute"`.

    - **`source_cap_equals_flow_cap`** *(boolean)*: If true, the decision variables `source_cap` and `flow_cap` are forced to equal one another. Default: `false`.

    - **`source_eff`**: Conversion efficiency from the technology from `source`. Set as value between 1 (no loss) and 0 (all lost). Refer to *[#/$defs/TechParamNullNumber](#%24defs/TechParamNullNumber)*. Default: `1.0`.

    - **`source_use_min`**: Minimum source use to add a carrier from the system (e.g., biofuel, coal, rainfall, wind flow). Unit dictated by `source_unit`. Refer to *[#/$defs/TechParamNullNumber](#%24defs/TechParamNullNumber)*. Default: `0`.

    - **`source_use_max`**: Maximum sink use to remove a carrier from the system (e.g., biofuel, coal, rainfall, wind flow). Unit dictated by `source_unit`. Refer to *[#/$defs/TechParamNullNumber](#%24defs/TechParamNullNumber)*. Default: `Infinity`.

    - **`source_use_equals`**: Required amount of carrier removal from the system (e.g., biofuel, coal, rainfall, wind flow). Unit dictated by `source_unit`. Refer to *[#/$defs/TechParamNullNumber](#%24defs/TechParamNullNumber)*. Default: `NaN`.

    - **`source_cap`**: Sets `source_cap` to a parameter in operate mode. NOTE: this parameter cannot be used in `plan` mode as it clashes with the decision variable of the same name. Refer to *[#/$defs/TechParamNullNumber](#%24defs/TechParamNullNumber)*. Default: `Infinity`.

    - **`source_cap_max`** *(number)*: Upper limit on `source_cap` decision variable. Default: `Infinity`.

    - **`source_cap_min`** *(number)*: Lower limit on `source_cap` decision variable. Default: `0`.

    - **`one_way`** *(boolean)*: Forces a transmission technology to only move flow in one direction on the link, i.e. from `link_from` to `link_to`. Default: `false`.

    - **`distance`** *(['null', 'number'])*: Used for `..._per_distance` constraints. If not defined, it will be automatically derived from latitude/longitude of nodes in a link. Default: `1.0`.

    - **`flow_in_eff_per_distance`**: Total link efficiency will be calculated as $\text{flow\_in\_eff}\times{}\text{flow\_in\_eff\_per\_distance}^\text{distance}$. Set as value between 1 (no loss) and 0 (all lost). Refer to *[#/$defs/TechParamNullNumber](#%24defs/TechParamNullNumber)*. Default: `1.0`.

    - **`flow_out_eff_per_distance`**: Total link efficiency will be calculated as $\text{flow\_out\_eff}\times{}\text{flow\_out\_eff\_per\_distance}^\text{distance}$. Set as value between 1 (no loss) and 0 (all lost). Refer to *[#/$defs/TechParamNullNumber](#%24defs/TechParamNullNumber)*. Default: `1.0`.

    - **`cost_flow_cap_per_distance`**: Cost per unit of the decision variable `flow_cap` and per unit distance of a transmission link. Applied to transmission links only. Refer to *[#/$defs/TechCostNullNumber](#%24defs/TechCostNullNumber)*. Default: `0`.

    - **`cost_purchase_per_distance`**: Cost applied if the binary variable `purchased` is 1 or per unit of the integer variable `units`. Requires the parameter `cap_method` to be `integer`. Refer to *[#/$defs/TechCostNullNumber](#%24defs/TechCostNullNumber)*. Default: `0`.

    - **`cost_flow_cap`**: Cost per unit of the decision variable `flow_cap`. Refer to *[#/$defs/TechCostNullNumber](#%24defs/TechCostNullNumber)*. Default: `0`.

    - **`cost_export`**: Cost per unit of `flow_export` in each timestep. Usually used in the negative sense, as a subsidy. Refer to *[#/$defs/TechCostNullNumber](#%24defs/TechCostNullNumber)*. Default: `0`.

    - **`cost_interest_rate`**: Used when computing levelized costs and technology depreciation_rate (relative to lifetime). Refer to *[#/$defs/TechCostNullNumber](#%24defs/TechCostNullNumber)*. Default: `0`.

    - **`cost_om_annual`**: Annual costs applied per unit `flow_cap`. These costs are not subject to being recalculated relative to technology lifetime, only scaled to reflect the fraction of one year that the model represents (e.g., 7 days ~= 0.02 of a year). Refer to *[#/$defs/TechCostNullNumber](#%24defs/TechCostNullNumber)*. Default: `0`.

    - **`cost_om_annual_investment_fraction`**: Add a fraction of the sum of all investment costs except `cost_om_annual` as an additional cost, to represent fixed annual O&M costs. Warning: the sum of all investment costs includes not just those associated with `flow_cap` but also others like those associated with `area_use`! Refer to *[#/$defs/TechCostNullNumber](#%24defs/TechCostNullNumber)*. Default: `0`.

    - **`cost_flow_in`**: Cost per unit of `flow_in` in each timestep. Refer to *[#/$defs/TechCostNullNumber](#%24defs/TechCostNullNumber)*. Default: `0`.

    - **`cost_flow_out`**: Cost per unit of `flow_in` in each timestep. Refer to *[#/$defs/TechCostNullNumber](#%24defs/TechCostNullNumber)*. Default: `0`.

    - **`cost_purchase`**: Cost applied to the variable `purchased_units`. Requires the parameter `cap_method` to be `integer`. Refer to *[#/$defs/TechCostNullNumber](#%24defs/TechCostNullNumber)*. Default: `0`.

    - **`cost_area_use`**: Cost per unit `area_use`. Refer to *[#/$defs/TechCostNullNumber](#%24defs/TechCostNullNumber)*. Default: `0`.

    - **`cost_source_cap`**: Cost per unit `source_cap`. Refer to *[#/$defs/TechCostNullNumber](#%24defs/TechCostNullNumber)*. Default: `0`.

    - **`cost_storage_cap`**: Cost per unit `storage_cap`, i.e., the maximum available capacity of the storage technology's "reservoir". Refer to *[#/$defs/TechCostNullNumber](#%24defs/TechCostNullNumber)*. Default: `0`.

    - **`cost_depreciation_rate`**: Applied to "annualise" investment costs so they are comparable to variable costs. If not provided, this will be calculated using technology `lifetime` and `cost_interest_rate`. Refer to *[#/$defs/TechCostNullNumber](#%24defs/TechCostNullNumber)*. Default: `1`.

    - **`^(cost_[\w]+)$`**: Refer to *[#/$defs/TechCostNullNumber](#%24defs/TechCostNullNumber)*.

nodes (object): Calliope model node definitions. Cannot contain additional properties.
- ^[^_^\d][\w]*$ (object): Can contain unevaluated properties.
  - Unevaluated properties
    - One of
      - : Refer to #/$defs/unIndexedParamVal.
      - object: Indexed tech-level parameter with any dtype. Cannot contain additional properties.
        
        data: Refer to #/$defs/IndexedParamData.
        
        index: Refer to #/$defs/IndexedParamIndex.
        
        dims: Refer to #/$defs/TechDims.
  - active: Refer to #/$defs/ActiveDef.
  - latitude (number): Minimum: -90. Maximum: 90.
  - longitude (number): Minimum: -180. Maximum: 180.
  - available_area (number): Limits the total area that can be occupied by all technologies which have the area_use decision variable activated. Minimum: 0. Default: Infinity.
  - ^(cost_[\w]+)$: Refer to #/$defs/TechCostNullNumber.

Definitions¶

unIndexedParamVal (['string', 'boolean', 'number', 'null']): zero-dimensional (i.e., un-indexed) parameter.
IndexedParamIndex: Model dimension members to apply the parameter value(s) to. If an array of arrays, sub-arrays must have same length as number of dims.
- One of
  - ['string', 'integer', 'number']
  - array: Length must be at least 1.
    - Items
      - One of
        
        array: Length must be at least 1.
        
        Items (['string', 'integer', 'number'])
        
        ['string', 'integer', 'number']
IndexedParamData: parameter value(s). If data is one value, will be applied to all dimension members. If a list, must be same length as the index array.
- One of
  - ['string', 'boolean', 'integer', 'number', 'null']
  - array: Length must be at least 1.
    - Items (['string', 'boolean', 'integer', 'number', 'null'])
IndexedParam (object): Indexed parameter. Cannot contain additional properties.
- data: Refer to #/$defs/IndexedParamData.
- index: Refer to #/$defs/IndexedParamIndex.
- dims: Model dimension(s) over which the parameter is indexed. Must be same length as the sub-arrays of index (if indexed does not have any sub-arrays or is simply a single value, dims must be of length 1).
  - One of
    - string
    - array: Length must be at least 1.
      - Items (string)
TechDims
TechCostDims: Model dimension(s) over which the parameter is indexed. Must be same length as the sub-arrays of index (if indexed does not have any sub-arrays or is simply a single value, dims must be of length 1). Cannot include techs or nodes as these will be added automatically in preprocessing. Must include costs as the string or as an element of the array.
- One of
  - string: Must be one of: ["costs"].
  - array: Length must be at least 1.
    - Items (string)
TechParamNullNumber
- One of
  - ['null', 'number']
  - object: Indexed tech-level parameter with null/numeric dtype. Cannot contain additional properties.
    - data: parameter value(s). If data is one value, will be applied to all dimension members. If a list, must be same length as the index array.
      - One of
        
        null
        
        number: Minimum: 0.
        
        array: Length must be at least 1.
        
        Items
        
        One of
        
        null
        
        number: Minimum: 0.
    - index: Refer to #/$defs/IndexedParamIndex.
    - dims: Refer to #/$defs/TechDims.
TechCostNullNumber
- One of
  - ['null', 'number']
  - object: Indexed tech-level cost. Cannot contain additional properties.
    - data: parameter value(s). If data is one value, will be applied to all dimension members. If a list, must be same length as the index array.
      - One of
        
        null
        
        number
        
        array: Length must be at least 1.
        
        Items
        
        One of
        
        null
        
        number
    - index: Refer to #/$defs/IndexedParamIndex.
    - dims: Refer to #/$defs/TechCostDims.
ActiveDef (boolean): If false, the model component (tech/node/link) will not make its way through to preprocessing. If a node, links between this node and others, via transmission technologies, will also be deactivated. Default: true.