Model math schema

*Calliope mathematical definition.

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

• constraints (object, required): All constraints to apply to the optimisation problem.

  • ^[^_^\d][\w]*$ (object): Schema for named constraints. Cannot contain additional properties.

    • title: The component long name, for use in visualisation. Default: null.

      • Any of

        • string

        • null

    • description: A verbose description of the component. Default: null.

      • Any of

        • string

        • null

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

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

      • Any of

        • array

          • Items (string)

        • null

    • where: 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. Default: null.

      • Any of

        • string

        • null

    • equations (array, required): Constraint math equations.

      • Items (object): Equation item schema.
        Equations may define conditions (where) defining on which index items in the product of sets (foreach) they will be applied. Conditions must be set up such that a maximum of one equation can be applied per index item. Cannot contain additional properties.

        • where: 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. Default: null.

          • Any of

            • string

            • null

        • expression (string, required): Equation expression valid for this component in the form LHS OPERATOR RHS, where LHS and RHS are math expressions and OPERATOR is one of [==, <=, >=].

    • sub_expressions: Constraint named sub-expressions. Default: null.

      • Any of

        • object

          • ^[^_^\d][\w]*$ (array)

            • Items (object): Sub-expression item schema.
              Math sub-expressions which are used to replace any instances in which they are referenced in a component's equations. They must be referenced by their name preceded with the "$" symbol, e.g., foo in $foo == 1 or $foo + 1. Cannot contain additional properties.

              • where: Condition to determine whether the accompanying sub-expression is built. Default: null.

                • Any of

                  • string

                  • null

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

        • null

    • slices: Constraint named index slices. Default: null.

      • Any of

        • object

          • ^[^_^\d][\w]*$ (array)

            • Items (object): Slice item schema.
              Array index slices which are used to replace any instances in which they are referenced in a component's equations or sub-expressions. They must be referenced by their name preceded with the "$" symbol, e.g., foo in flow_out_eff[techs=$foo]. Cannot contain additional properties.

              • where: Condition to determine whether the accompanying index slice is built. Default: null.

                • Any of

                  • string

                  • null

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

        • null

• piecewise_constraints: All piecewise constraints to apply to the optimisation problem. Default: null.

  • Any of

    • object

      • ^[^_^\d][\w]*$ (object): Schema for named piece-wise constraints.
        These link an x-axis decision variable with a y-axis decision variable with values at specified breakpoints. Cannot contain additional properties.

        • title: The component long name, for use in visualisation. Default: null.

          • Any of

            • string

            • null

        • description: A verbose description of the component. Default: null.

          • Any of

            • string

            • null

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

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

          • Any of

            • array

              • Items (string)

            • null

        • where: 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. Default: null.

          • Any of

            • string

            • null

        • x_expression (string, required): X variable name whose values are assigned at each breakpoint.

        • y_expression (string, required): Y variable name whose values are assigned at each breakpoint.

        • x_values (string, required): X parameter name containing data, indexed over the breakpoints dimension.

        • y_values (string, required): Y parameter name containing data, indexed over the breakpoints dimension.

    • null

• global_expressions: All global expressions that can be applied to the optimisation problem. Default: null.

  • Any of

    • object

      • ^[^_^\d][\w]*$ (object): Schema for named global expressions.
        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.

        • title: The component long name, for use in visualisation. Default: null.

          • Any of

            • string

            • null

        • description: A verbose description of the component. Default: null.

          • Any of

            • string

            • null

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

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

          • Any of

            • array

              • Items (string)

            • null

        • where: 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. Default: null.

          • Any of

            • string

            • null

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

          • Any of

            • string

            • null

        • default: If set, will be the default value for the expression. Default: null.

          • Any of

            • number

            • null

        • equations (array, required): Global expression math equations.

          • Items (object): Equation item schema.
            Equations may define conditions (where) defining on which index items in the product of sets (foreach) they will be applied. Conditions must be set up such that a maximum of one equation can be applied per index item. Cannot contain additional properties.

            • where: 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. Default: null.

              • Any of

                • string

                • null

            • expression (string, required): Equation expression valid for this component in the form LHS OPERATOR RHS, where LHS and RHS are math expressions and OPERATOR is one of [==, <=, >=].

        • sub_expressions: Global expression named sub-expressions. Default: null.

          • Any of

            • object

              • ^[^_^\d][\w]*$ (array)

                • Items (object): Sub-expression item schema.
                  Math sub-expressions which are used to replace any instances in which they are referenced in a component's equations. They must be referenced by their name preceded with the "$" symbol, e.g., foo in $foo == 1 or $foo + 1. Cannot contain additional properties.

                  • where: Condition to determine whether the accompanying sub-expression is built. Default: null.

                    • Any of

                      • string

                      • null

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

            • null

        • slices: Global expression named index slices. Default: null.

          • Any of

            • object

              • ^[^_^\d][\w]*$ (array)

                • Items (object): Slice item schema.
                  Array index slices which are used to replace any instances in which they are referenced in a component's equations or sub-expressions. They must be referenced by their name preceded with the "$" symbol, e.g., foo in flow_out_eff[techs=$foo]. Cannot contain additional properties.

                  • where: Condition to determine whether the accompanying index slice is built. Default: null.

                    • Any of

                      • string

                      • null

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

            • null

    • null

• variables (object, required): All decision variables to include in the optimisation problem.

  • ^[^_^\d][\w]*$ (object): Schema for optimisation problem variables.
    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.

    • title: The component long name, for use in visualisation. Default: null.

      • Any of

        • string

        • null

    • description: A verbose description of the component. Default: null.

      • Any of

        • string

        • null

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

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

      • Any of

        • array

          • Items (string)

        • null

    • where: 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. Default: null.

      • Any of

        • string

        • null

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

      • Any of

        • string

        • null

    • default: If set, will be the default value for the variable. Default: null.

      • Any of

        • number

        • null

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

    • bounds (object, required): Bounds of decision variables.
      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.

      • max: Decision variable upper bound, either as a reference to an input parameter or as a number. Default: null.

        • Any of

          • string

          • number

          • null

      • min: Decision variable lower bound, either as a reference to an input parameter or as a number. Default: null.

        • Any of

          • string

          • number

          • null

• objectives (object, required): Possible objectives to apply to the optimisation problem.

  • ^[^_^\d][\w]*$ (object): Schema for optimisation problem objectives.
    Only one objective, the one referenced in model configuration build.objective will be activated for the optimisation problem. Cannot contain additional properties.

    • title: The component long name, for use in visualisation. Default: null.

      • Any of

        • string

        • null

    • description: A verbose description of the component. Default: null.

      • Any of

        • string

        • null

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

    • equations (array, required): Objective math equations.

      • Items (object): Equation item schema.
        Equations may define conditions (where) defining on which index items in the product of sets (foreach) they will be applied. Conditions must be set up such that a maximum of one equation can be applied per index item. Cannot contain additional properties.

        • where: 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. Default: null.

          • Any of

            • string

            • null

        • expression (string, required): Equation expression valid for this component in the form LHS OPERATOR RHS, where LHS and RHS are math expressions and OPERATOR is one of [==, <=, >=].

    • sub_expressions: Objective named sub-expressions. Default: null.

      • Any of

        • object

          • ^[^_^\d][\w]*$ (array)

            • Items (object): Sub-expression item schema.
              Math sub-expressions which are used to replace any instances in which they are referenced in a component's equations. They must be referenced by their name preceded with the "$" symbol, e.g., foo in $foo == 1 or $foo + 1. Cannot contain additional properties.

              • where: Condition to determine whether the accompanying sub-expression is built. Default: null.

                • Any of

                  • string

                  • null

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

        • null

    • slices: Objective named index slices. Default: null.

      • Any of

        • object

          • ^[^_^\d][\w]*$ (array)

            • Items (object): Slice item schema.
              Array index slices which are used to replace any instances in which they are referenced in a component's equations or sub-expressions. They must be referenced by their name preceded with the "$" symbol, e.g., foo in flow_out_eff[techs=$foo]. Cannot contain additional properties.

              • where: Condition to determine whether the accompanying index slice is built. Default: null.

                • Any of

                  • string

                  • null

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

        • null

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