Math formulation schema

All options available to formulate math to use in solving an optimisation problem with Calliope.

• constraints (object): All constraints to apply to the optimisation problem. Cannot contain additional properties.

  • [^\d^_\W][\w\d]+ (object): A named constraint. Cannot contain additional properties.

    • description (string): A verbose description of the component.

    • active (boolean): If False, this component will be ignored entirely at the optimisation problem build phase.

    • foreach (array): sets (a.k.a. dimensions) of the model over which the math formulation component will be built.

      • Items (string): Calliope set name (e.g., "techs", "nodes").

    • where (string): Top-level condition to determine whether the component exists in this optimisation problem (at all, if foreach is not given, or for specific index items within the product of the sets given by foreach).

    • equations (array, required): Constraint math equations with conditions defining on which index items in the product of foreach sets they will be applied. Conditions must be set up such that a maximum of one equation can be applied per index item. Equations are of the form LHS OPERATOR RHS, where LHS and RHS are math expressions and OPERATOR is one of [==, <=, >=].

      • Items (object): Cannot contain additional properties.

        • where (string): Condition to determine whether the accompanying expression is built (at all, if foreach is not given, or for specific index items within the product of the sets given by foreach).

        • expression (string, required): Equation expression valid for this component type (see component equations description).

    • sub_expressions (object): Math sub-expressions which are used to replace any instances in which they are referenced in the component equation(s). Sub-expressions are referenced by their name preceded with the "$" symbol, e.g., foo in $foo == 1 or $foo + 1. Cannot contain additional properties.

      • [^\d^_\W][\w\d]+ (array): Named sub-expression.

        • Items (object): Cannot contain additional properties.

          • where (string): Condition to determine whether the accompanying sub-expression is built.

          • expression (string, required): math equation sub-expression which can be one term or a combination of terms using the operators [+, -, , /, *].

    • slices (object): Array index slices which are used to replace any instances in which they are referenced in decision variables/parameters/global expressions in the component equation(s) or sub-expressions. Index slices are referenced by their name preceded with the "$" symbol, e.g., foo in flow_out_eff[techs=$foo]. Cannot contain additional properties.

      • [^\d^_\W][\w\d]+ (array): Named Index slice.

        • Items (object): Cannot contain additional properties.

          • where (string): Condition to determine whether the accompanying index slice is built.

          • expression (string, required): Index slice expression, such as a list of set items or a call to a helper function.

• global_expressions (object): Definition of global expressions that can be used to combine parameters and variables and then used in one or more expressions elsewhere in the math formulation (i.e., in constraints, objectives, and other global expressions). NOTE: If expecting to use global expression A in global expression B, A must be defined above B. Cannot contain additional properties.

  • [^\d^_\W][\w\d]+ (object): A named global expression. Cannot contain additional properties.

    • description (string): A verbose description of the component.

    • active (boolean): If False, this component will be ignored entirely at the optimisation problem build phase.

    • unit (string): Generalised unit of the component (e.g., length, time, quantity_per_hour, ...).

    • default (number)

    • foreach (array): sets (a.k.a. dimensions) of the model over which the math formulation component will be built.

      • Items (string): Calliope set name (e.g., "techs", "nodes").

    • where (string): Top-level condition to determine whether the component exists in this optimisation problem (at all, if foreach is not given, or for specific index items within the product of the sets given by foreach).

    • equations (array, required): Math equation expressions with conditions defining on which index items in the product of foreach sets they will be applied. Conditions must be set up such that a maximum of one equation expression can be applied per index item. Equation expression combining terms with the operators [+, -, , /, *].

      • Items (object): Cannot contain additional properties.

        • where (string): Condition to determine whether the accompanying expression is built (at all, if foreach is not given, or for specific index items within the product of the sets given by foreach).

        • expression (string, required): Equation expression valid for this component type (see component equations description).

    • sub_expressions (object): Math sub-expressions which are used to replace any instances in which they are referenced in the component equation(s). Sub-expressions are referenced by their name preceded with the "$" symbol, e.g., foo in $foo == 1 or $foo + 1. Cannot contain additional properties.

      • [^\d^_\W][\w\d]+ (array): Named sub-expression.

        • Items (object): Cannot contain additional properties.

          • where (string): Condition to determine whether the accompanying sub-expression is built.

          • expression (string, required): math equation sub-expression which can be one term or a combination of terms using the operators [+, -, , /, *].

    • slices (object): Array index slices which are used to replace any instances in which they are referenced in decision variables/parameters/global expressions in the component equation(s) or sub-expressions. Index slices are referenced by their name preceded with the "$" symbol, e.g., foo in flow_out_eff[techs=$foo]. Cannot contain additional properties.

      • [^\d^_\W][\w\d]+ (array): Named Index slice.

        • Items (object): Cannot contain additional properties.

          • where (string): Condition to determine whether the accompanying index slice is built.

          • expression (string, required): Index slice expression, such as a list of set items or a call to a helper function.

• variables (object): Decision variables to include in the optimisation problem. A decision variable must be referenced in at least one constraint or in the objective for it to exist in the optimisation problem that is sent to the solver. Cannot contain additional properties.

  • [^\d^_\W][\w\d]+ (object): A named variable. Cannot contain additional properties.

    • description (string): A verbose description of the component.

    • active (boolean): If False, this component will be ignored entirely at the optimisation problem build phase.

    • unit (string): Generalised unit of the component (e.g., length, time, quantity_per_hour, ...).

    • default (number)

    • foreach (array): sets (a.k.a. dimensions) of the model over which the math formulation component will be built.

      • Items (string): Calliope set name (e.g., "techs", "nodes").

    • where (string): Top-level condition to determine whether the component exists in this optimisation problem (at all, if foreach is not given, or for specific index items within the product of the sets given by foreach).

    • domain (string): Allowed values that the decision variable can take (either integer or continuous, a.k.a. real, values). Must be one of: ["real", "integer"].

    • bounds (object): Upper and lower bounds of the decision variable, either derived per-index item from a multi-dimensional input parameter, or given as a single value that is applied across all decision variable index items. Cannot contain additional properties.

      • min (['string', 'number']): Decision variable lower bound, either as a reference to an input parameter or as a number.

      • max (['string', 'number']): Decision variable upper bound, either as a reference to an input parameter or as a number.

• objectives (object): Possible objectives to apply to the optimisation problem. Only one objective, the one referenced in model configuration run.objective will be activated for the optimisation problem. Cannot contain additional properties.

  • [^\d^_\W][\w\d]+ (object): A named variable. Cannot contain additional properties.

    • description (string): A verbose description of the component.

    • active (boolean): If False, this component will be ignored entirely at the optimisation problem build phase.

    • equations (array, required): Math equation expressions with conditions to determine which expression will be applied for this objectives. Conditions must be set up such that only one equation expression can be applied for this objective.

      • Items (object): Cannot contain additional properties.

        • where (string): Condition to determine whether the accompanying expression is built (at all, if foreach is not given, or for specific index items within the product of the sets given by foreach).

        • expression (string, required): Equation expression valid for this component type (see component equations description).

    • sub_expressions (object): Math sub-expressions which are used to replace any instances in which they are referenced in the component equation(s). Sub-expressions are referenced by their name preceded with the "$" symbol, e.g., foo in $foo == 1 or $foo + 1. Cannot contain additional properties.

      • [^\d^_\W][\w\d]+ (array): Named sub-expression.

        • Items (object): Cannot contain additional properties.

          • where (string): Condition to determine whether the accompanying sub-expression is built.

          • expression (string, required): math equation sub-expression which can be one term or a combination of terms using the operators [+, -, , /, *].

    • slices (object): Array index slices which are used to replace any instances in which they are referenced in decision variables/parameters/global expressions in the component equation(s) or sub-expressions. Index slices are referenced by their name preceded with the "$" symbol, e.g., foo in flow_out_eff[techs=$foo]. Cannot contain additional properties.

      • [^\d^_\W][\w\d]+ (array): Named Index slice.

        • Items (object): Cannot contain additional properties.

          • where (string): Condition to determine whether the accompanying index slice is built.

          • expression (string, required): Index slice expression, such as a list of set items or a call to a helper function.

    • sense (string): Whether the objective function should be minimised or maximised in the optimisation. Must be one of: ["minimise", "maximise", "minimize", "maximize"].