Model math schema

*Mathematical definition of Calliope math.

Contains mathematical programming components available for optimising with Calliope. Can contain partial definitions if they are meant to be layered on top of another. E.g.: layering 'base' and 'operate' math.*

• dimensions (object): Calliope model dimensions dictionary.

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

    • title (string): The component long name, for use in visualisation. Default: "".

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

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

    • dtype (string): The data type of this dimension's items. Must be one of: "string", "datetime", "date", "float", or "integer". Default: "string".

    • ordered (boolean): If True, the order of the dimension items is meaningful (e.g. chronological time). Default: false.

    • iterator (string): The name of the iterator to use in the LaTeX math formulation for this dimension. Default: "NEEDS_ITERATOR".

• parameters (object): Calliope model parameters dictionary.

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

    • title (string): The component long name, for use in visualisation. Default: "".

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

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

    • default: The default value for the parameter, if not set in the data. Default: NaN.

      • Any of

        • number

        • integer

    • resample_method (string): If resampling is applied over any of the parameter's dimensions, the method to use to aggregate the data. Must be one of: "mean", "sum", or "first". Default: "first".

    • unit (string): The unit of the parameter, e.g. 'kW', 'm', 'kg', 'energy', 'power', ... Default: "".

• lookups (object): Calliope model lookup dictionary.

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

    • title (string): The component long name, for use in visualisation. Default: "".

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

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

    • default: The default value for the lookup, if not set in the data. Default: NaN.

      • Any of

        • string: Must match pattern: ^[^_^\d][\w]*$ (Test).

        • number

        • integer

        • boolean

    • dtype (string): The lookup data type. Must be one of: "float", "string", "bool", "datetime", or "date". Default: "string".

    • resample_method (string): If resampling is applied over any of the lookup's dimensions, the method to use to aggregate the data. Must be one of: "mean", "sum", or "first". Default: "first".

    • one_of: If given, the lookup values must be one of these items. Default: null.

      • Any of

        • array

        • null

    • pivot_values_to_dim: If given, the lookup will be pivoted such that its values become the index of a new dimension and its new values are boolean, True where the index values match the old values. For instance, if the lookup starts out indexed over techs with values of [electricity, gas] and pivot_values_to_dim: carriers, then the lookup will be converted to a boolean array with the dimensions ['techs', 'carriers']. Default: null.

      • Any of

        • string

        • null

• variables (object): Calliope model variables dictionary.

  • ^[^_^\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 (string): The component long name, for use in visualisation. Default: "".

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

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

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

      • Items (string): Must match pattern: ^[^_^\d][\w]*$ (Test).

    • 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. Default: "True".

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

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

      • Any of

        • integer

        • number

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

    • bounds (object): 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: Infinity.

        • Any of

          • string: Must match pattern: ^[^_^\d][\w]*$ (Test).

          • integer

          • number

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

        • Any of

          • string: Must match pattern: ^[^_^\d][\w]*$ (Test).

          • integer

          • number

• global_expressions (object): Calliope model global_expressions dictionary.

  • ^[^_^\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 (string): The component long name, for use in visualisation. Default: "".

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

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

    • equations (array): List of equations that can be updated when a parent pydantic model is updated.

      • Items (object): Schema for equations, subexpressions and slices. Cannot contain additional properties.

        • where (string): Condition to determine whether the accompanying expression is built. Default: "True".

        • expression (string, required): Expression for this component.

        • Equations: LHS OPERATOR RHS, where LHS and RHS are math expressions and OPERATOR is one of [==, <=, >=].
        • Subexpressions: be one term or a combination of terms using the operators [+, -, , /, *].
        • Slices: a list of set items or a call to a helper function.

    • sub_expressions (object): Dictionary of sub-expressions that can be updated when a parent pydantic model is updated.

      • ^[^_^\d][\w]*$ (array): List of equations that can be updated when a parent pydantic model is updated.

        • Items (object): Schema for equations, subexpressions and slices. Cannot contain additional properties.

          • where (string): Condition to determine whether the accompanying expression is built. Default: "True".

          • expression (string, required): Expression for this component.

          • Equations: LHS OPERATOR RHS, where LHS and RHS are math expressions and OPERATOR is one of [==, <=, >=].
          • Subexpressions: be one term or a combination of terms using the operators [+, -, , /, *].
          • Slices: a list of set items or a call to a helper function.

    • slices (object): Dictionary of sub-expressions that can be updated when a parent pydantic model is updated.

      • ^[^_^\d][\w]*$ (array): List of equations that can be updated when a parent pydantic model is updated.

        • Items (object): Schema for equations, subexpressions and slices. Cannot contain additional properties.

          • where (string): Condition to determine whether the accompanying expression is built. Default: "True".

          • expression (string, required): Expression for this component.

          • Equations: LHS OPERATOR RHS, where LHS and RHS are math expressions and OPERATOR is one of [==, <=, >=].
          • Subexpressions: be one term or a combination of terms using the operators [+, -, , /, *].
          • Slices: a list of set items or a call to a helper function.

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

      • Items (string): Must match pattern: ^[^_^\d][\w]*$ (Test).

    • 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. Default: "True".

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

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

      • Any of

        • integer

        • number

    • order (integer): Order in which to apply this global expression relative to all others, if different to its definition order. Default: 0.

• constraints (object): Calliope model constraints dictionary.

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

    • title (string): The component long name, for use in visualisation. Default: "".

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

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

    • equations (array): List of equations that can be updated when a parent pydantic model is updated.

      • Items (object): Schema for equations, subexpressions and slices. Cannot contain additional properties.

        • where (string): Condition to determine whether the accompanying expression is built. Default: "True".

        • expression (string, required): Expression for this component.

        • Equations: LHS OPERATOR RHS, where LHS and RHS are math expressions and OPERATOR is one of [==, <=, >=].
        • Subexpressions: be one term or a combination of terms using the operators [+, -, , /, *].
        • Slices: a list of set items or a call to a helper function.

    • sub_expressions (object): Dictionary of sub-expressions that can be updated when a parent pydantic model is updated.

      • ^[^_^\d][\w]*$ (array): List of equations that can be updated when a parent pydantic model is updated.

        • Items (object): Schema for equations, subexpressions and slices. Cannot contain additional properties.

          • where (string): Condition to determine whether the accompanying expression is built. Default: "True".

          • expression (string, required): Expression for this component.

          • Equations: LHS OPERATOR RHS, where LHS and RHS are math expressions and OPERATOR is one of [==, <=, >=].
          • Subexpressions: be one term or a combination of terms using the operators [+, -, , /, *].
          • Slices: a list of set items or a call to a helper function.

    • slices (object): Dictionary of sub-expressions that can be updated when a parent pydantic model is updated.

      • ^[^_^\d][\w]*$ (array): List of equations that can be updated when a parent pydantic model is updated.

        • Items (object): Schema for equations, subexpressions and slices. Cannot contain additional properties.

          • where (string): Condition to determine whether the accompanying expression is built. Default: "True".

          • expression (string, required): Expression for this component.

          • Equations: LHS OPERATOR RHS, where LHS and RHS are math expressions and OPERATOR is one of [==, <=, >=].
          • Subexpressions: be one term or a combination of terms using the operators [+, -, , /, *].
          • Slices: a list of set items or a call to a helper function.

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

      • Items (string): Must match pattern: ^[^_^\d][\w]*$ (Test).

    • 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. Default: "True".

• piecewise_constraints (object): Calliope model piecewise_constraints dictionary.

  • ^[^_^\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 (string): The component long name, for use in visualisation. Default: "".

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

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

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

      • Items (string): Must match pattern: ^[^_^\d][\w]*$ (Test).

    • 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. Default: "True".

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

• objectives (object): Calliope model objectives dictionary.

  • ^[^_^\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 (string): The component long name, for use in visualisation. Default: "".

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

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

    • equations (array): List of equations that can be updated when a parent pydantic model is updated.

      • Items (object): Schema for equations, subexpressions and slices. Cannot contain additional properties.

        • where (string): Condition to determine whether the accompanying expression is built. Default: "True".

        • expression (string, required): Expression for this component.

        • Equations: LHS OPERATOR RHS, where LHS and RHS are math expressions and OPERATOR is one of [==, <=, >=].
        • Subexpressions: be one term or a combination of terms using the operators [+, -, , /, *].
        • Slices: a list of set items or a call to a helper function.

    • sub_expressions (object): Dictionary of sub-expressions that can be updated when a parent pydantic model is updated.

      • ^[^_^\d][\w]*$ (array): List of equations that can be updated when a parent pydantic model is updated.

        • Items (object): Schema for equations, subexpressions and slices. Cannot contain additional properties.

          • where (string): Condition to determine whether the accompanying expression is built. Default: "True".

          • expression (string, required): Expression for this component.

          • Equations: LHS OPERATOR RHS, where LHS and RHS are math expressions and OPERATOR is one of [==, <=, >=].
          • Subexpressions: be one term or a combination of terms using the operators [+, -, , /, *].
          • Slices: a list of set items or a call to a helper function.

    • slices (object): Dictionary of sub-expressions that can be updated when a parent pydantic model is updated.

      • ^[^_^\d][\w]*$ (array): List of equations that can be updated when a parent pydantic model is updated.

        • Items (object): Schema for equations, subexpressions and slices. Cannot contain additional properties.

          • where (string): Condition to determine whether the accompanying expression is built. Default: "True".

          • expression (string, required): Expression for this component.

          • Equations: LHS OPERATOR RHS, where LHS and RHS are math expressions and OPERATOR is one of [==, <=, >=].
          • Subexpressions: be one term or a combination of terms using the operators [+, -, , /, *].
          • Slices: a list of set items or a call to a helper function.

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

• postprocessed (object): Calliope model postprocessed expressions dictionary.

  • ^[^_^\d][\w]*$ (object): Schema for postprocessed expressions.
    Can be used to combine parameters, variables, and global expressions into a single expression solving the model.
    NOTE: If expecting to use postprocessed array A in postprocessed array B, A must be defined above B. Cannot contain additional properties.

    • title (string): The component long name, for use in visualisation. Default: "".

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

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

    • equations (array): List of equations that can be updated when a parent pydantic model is updated.

      • Items (object): Schema for equations, subexpressions and slices. Cannot contain additional properties.

        • where (string): Condition to determine whether the accompanying expression is built. Default: "True".

        • expression (string, required): Expression for this component.

        • Equations: LHS OPERATOR RHS, where LHS and RHS are math expressions and OPERATOR is one of [==, <=, >=].
        • Subexpressions: be one term or a combination of terms using the operators [+, -, , /, *].
        • Slices: a list of set items or a call to a helper function.

    • sub_expressions (object): Dictionary of sub-expressions that can be updated when a parent pydantic model is updated.

      • ^[^_^\d][\w]*$ (array): List of equations that can be updated when a parent pydantic model is updated.

        • Items (object): Schema for equations, subexpressions and slices. Cannot contain additional properties.

          • where (string): Condition to determine whether the accompanying expression is built. Default: "True".

          • expression (string, required): Expression for this component.

          • Equations: LHS OPERATOR RHS, where LHS and RHS are math expressions and OPERATOR is one of [==, <=, >=].
          • Subexpressions: be one term or a combination of terms using the operators [+, -, , /, *].
          • Slices: a list of set items or a call to a helper function.

    • slices (object): Dictionary of sub-expressions that can be updated when a parent pydantic model is updated.

      • ^[^_^\d][\w]*$ (array): List of equations that can be updated when a parent pydantic model is updated.

        • Items (object): Schema for equations, subexpressions and slices. Cannot contain additional properties.

          • where (string): Condition to determine whether the accompanying expression is built. Default: "True".

          • expression (string, required): Expression for this component.

          • Equations: LHS OPERATOR RHS, where LHS and RHS are math expressions and OPERATOR is one of [==, <=, >=].
          • Subexpressions: be one term or a combination of terms using the operators [+, -, , /, *].
          • Slices: a list of set items or a call to a helper function.

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

      • Items (string): Must match pattern: ^[^_^\d][\w]*$ (Test).

    • 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. Default: "True".

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

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

      • Any of

        • integer

        • number

    • order (integer): Order in which to apply this global expression relative to all others, if different to its definition order. Default: 0.

• checks (object): Calliope math checks dictionary.

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

    • where (string, required): Top-level condition to check.

    • message (string, required): Message to display when the where array returns True, if raising or warning on error.

    • errors (string): How to respond to any instances in which the where array returns True. Must be one of: "raise" or "warn". Default: "raise".

    • active (boolean): If False, this check will be ignored during the build phase. Default: true.