Skip to content

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]*$

  • 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
              • base_tech
              • base_tech
              • base_tech

              • base_tech

              • from (string, required): The resulting link technology will have flow_out == import and flow_in == export at this node.

              • to (string, required): The resulting link technology will have flow_out == import and flow_in == export at this node.

      • Unevaluated properties

      • 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: Limits flow_cap to a minimum. NOTE: this will force flow_cap to a minimum value unless cap_method is set to integer. If cap_method=integer, this will be scaled by the number of integer units of a technology purchased. 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. 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. 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. 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. 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. 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. 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. Default: 1.0.

      • export_max: If carrier_export is defined, limit the allowed export of produced carrier for a technology. Refer to #/$defs/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. 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. Default: Infinity.

      • area_use_min: Limits the lower bound of the area_use decision variable to this value. Refer to #/$defs/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. 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. Default: Infinity.

      • storage_cap_max: Limit upper bound of storage_cap decision variable. Refer to #/$defs/TechParamNullNumber. Default: Infinity.

      • storage_cap_min: Limit lower bound of storage_cap decision variable. Refer to #/$defs/TechParamNullNumber. Default: 0.

      • storage_cap_per_unit: Set the storage capacity of each integer unit of a technology purchased. Refer to #/$defs/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. Default: 0.

      • storage_initial: Set stored flow in device at the first timestep, as a fraction of total storage capacity. Refer to #/$defs/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. 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. 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. 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. Default: Infinity.

      • purchased_units_min: Limits the lower bound of units purchased if cap_method is integer. Refer to #/$defs/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. Default: Infinity.

      • sink_unit (string): Sets the unit of Sink to either absolute x-unit: energy), per_area x-unit: energy/area), or per_cap x-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 source_unit. Refer to #/$defs/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 source_unit. Refer to #/$defs/TechParamNullNumber. Default: Infinity.

      • sink_use_equals: Required amount of carrier removal from the system (e.g., electricity demand, transport distance). Unit dictated by source_unit. Refer to #/$defs/TechParamNullNumber. Default: NaN.

      • source_unit (string): Sets the unit of Source to either absolute (e.g. kWh), per_area (e.g. kWh/m2), or per_cap (e.g. kWh/kW). 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. 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. 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. 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. 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. 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 from to 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. 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. 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. 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. Default: 0.

      • cost_flow_cap: Cost per unit of the decision variable flow_cap. Refer to #/$defs/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. Default: 0.

      • cost_interest_rate: Used when computing levelized costs and technology depreciation_rate (relative to lifetime). Refer to #/$defs/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. Default: 0.

      • cost_om_annual_investment_fraction: Add an additional cost to total investment costs (except cost_om_annual) that is a fraction of that total. Refer to #/$defs/TechCostNullNumber. Default: 0.

      • cost_flow_in: Cost per unit of flow_in in each timestep. Refer to #/$defs/TechCostNullNumber. Default: 0.

      • cost_flow_out: Cost per unit of flow_in in each timestep. Refer to #/$defs/TechCostNullNumber. Default: 0.

      • cost_purchase: Cost applied to the variable purchased_units. Requires the parameter cap_method to be integer. Refer to #/$defs/TechCostNullNumber. Default: 0.

      • cost_area_use: Cost per unit area_use. Refer to #/$defs/TechCostNullNumber. Default: 0.

      • cost_source_cap: Cost per unit source_cap. Refer to #/$defs/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. 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. Default: 1.

      • ^(cost_[\w]+)$: Refer to #/$defs/TechCostNullNumber.

  • nodes (object): Calliope model node definitions. Cannot contain additional properties.

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 costsrun.objective.

    • 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.