Update to Callioepe v0.7.0dev3; fix docs and tests; add CI (#2)

.github/ISSUE_TEMPLATE/BUG-REPORT.yml

@@ -0,0 +1,38 @@
+name: Bug Report
+description: Report a bug that leads to calliope-pathways not working as expected.
+labels: [bug]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thanks for taking the time to fill out this bug report!
+  - type: textarea
+    id: what-happened
+    attributes:
+      label: What happened?
+      description: Also tell us what you expected to happen.
+      placeholder: Tell us what you see!
+      value: "Something unexpected happened!"
+    validations:
+      required: true
+  - type: textarea
+    id: operating-systems
+    attributes:
+      label: Which operating systems have you used?
+      description: You may select more than one.
+    validations:
+      required: true
+  - type: textarea
+    id: version
+    attributes:
+      label: Version
+      description: What version of calliope-pathways are you using?
+      placeholder: v0.1.0
+  - type: textarea
+    id: logs
+    attributes:
+      label: Relevant log output
+      description: Please copy and paste any relevant log output. This will be automatically formatted into code, so no need for backticks.
+      render: Shell
+    validations:
+      required: false

.github/ISSUE_TEMPLATE/DOCS.yml

@@ -0,0 +1,53 @@
+name: Report a documentation issue
+description: Missing, incorrect, or confusing information in our docs? Report a documentation issue
+labels:
+  - documentation
+body:
+  - type: textarea
+    id: description
+    attributes:
+      label: Description
+      description: >-
+        Please describe the inconsistency or issue you have found in
+        [our documentation](https://calliope-pathways.readthedocs.io)
+        or indicate where you feel there is a need for improvement. Furthermore,
+        explain the severity of the issue, i.e., its impact on you and potentially
+        other users.
+    validations:
+      required: true
+
+  - type: textarea
+    id: related-links
+    attributes:
+      label: Related links
+      description: >-
+        Please list all links to the sections of [our documentation](https://calliope-pathways.readthedocs.io)
+        that are impacted by the issue you described above. If applicable,
+        add screenshots. Additionally, list links to possibly related open
+        and closed [issues](https://github.com/calliope-project/calliope-pathways/issues)
+        and [discussions](https://github.com/calliope-project/calliope-pathways/discussions)
+        you encountered when searching our issue tracker.
+      value: |
+        -
+        -
+        ...
+    validations:
+      required: true
+
+  - type: textarea
+    id: version
+    attributes:
+      label: Version
+      description: Which version of the documentation are you referring to?
+      placeholder: v0.7.0
+    validations:
+      required: true
+
+  - type: textarea
+    id: proposed-change
+    attributes:
+      label: Proposed change
+      description: >-
+        This field is optional. You may provide an improvement proposal for our
+        documentation by describing your suggestion in the text field below or
+        creating a pull request after reporting this issue referencing the issue.

.github/ISSUE_TEMPLATE/FEATURE-REQUEST.yml

@@ -0,0 +1,24 @@
+name: Feature Request
+description: Suggest an idea for calliope-pathways.
+labels: [enhancement]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thanks for letting us know about your idea!
+  - type: textarea
+    id: description
+    attributes:
+      label: What can be improved?
+      placeholder: Tell us what you would like to see!
+      value: "calliope-pathways should be more memory efficient!"
+    validations:
+      required: true
+  - type: textarea
+    id: version
+    attributes:
+      label: Version
+      description: What version of calliope-pathways are you using?
+      placeholder: v0.1.0
+    validations:
+      required: true

.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1 @@
+blank_issues_enabled: true

.github/workflows/link-check.yml

@@ -0,0 +1,18 @@
+name: Markdown link check
+
+on:
+  schedule:  # runs every monday at 9 am
+    - cron: "0 9 * * 1"
+  pull_request:
+    branches:
+      - "main"
+    paths:
+      - "**.md"
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+      - name: markdown-link-check
+        uses: gaurav-nelson/github-action-markdown-link-check@1.0.15

.github/workflows/pr-ci.yml

@@ -0,0 +1,73 @@
+name: Pull Request CI
+
+on:
+  pull_request:
+    branches:
+      - "main"
+    paths-ignore:
+      - README.md
+      - CHANGELOG.md
+      - LICENSE
+      - AUTHORS
+      - docs/**
+      - .readthedocs.yml
+      - .pre-commit-config.yaml
+      - mkdocs.yml
+
+defaults:
+  run:
+    shell: bash -l {0}
+
+concurrency:
+  # Use github.run_id on main branch
+  # Use github.event.pull_request.number on pull requests, so it's unique per pull request
+  # Use github.ref on other branches, so it's unique per branch
+  group: ${{ github.workflow }}-${{ github.ref == 'refs/heads/main' && github.run_id || github.event.pull_request.number || github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  test:
+    if: github.event.pull_request.draft == false
+    strategy:
+      matrix:
+        os: [ubuntu-latest]
+        py3version: ["10", "11", "12"]
+        include:
+          - os: windows-latest
+            py3version: "12"
+          - os: macos-latest
+            py3version: "12"
+      fail-fast: false
+    runs-on: ${{ matrix.os }}
+    steps:
+    - uses: actions/checkout@v3
+
+    - uses: mamba-org/setup-micromamba@v1
+      with:
+        micromamba-version: latest
+        environment-name: ${{ github.event.repository.name }}-${{ matrix.os }}-3${{ matrix.py3version }}-${{ hashFiles('requirements/dev.txt') }}
+        environment-file: requirements/base.txt
+        create-args: >-
+          -c conda-forge/label/calliope_dev
+          -f requirements/dev.txt
+          curl
+          python=3.${{ matrix.py3version }}
+        post-cleanup: all
+        cache-environment: true
+
+    - name: Install package
+      run: pip install --no-dependencies -e .
+
+    - name: install CBC (Windows)
+      if: matrix.os == 'windows-latest'
+      run: |
+        curl -L https://github.com/coin-or/Cbc/releases/download/releases%2F2.10.10/Cbc-releases.2.10.10-w64-msvc17-md.zip -o cbc.zip
+        unzip cbc.zip -d ${HOME}/cbc
+        echo "${HOME}/cbc/bin" >> $GITHUB_PATH
+
+    - name: install CBC (Unix)
+      if: matrix.os != 'windows-latest'
+      run: micromamba install coin-or-cbc
+
+    - name: run tests
+      run: pytest

README.md

@@ -1,5 +1,7 @@
 # calliope-pathways
 
+[![Documentation Status](https://readthedocs.org/projects/calliope-pathways/badge/?version=latest)](https://calliope-pathways.readthedocs.io/en/latest/?badge=latest)
+
 Pathway optimisation implementation built on top of Calliope v0.7
 
 ## Install
@@ -10,12 +12,39 @@ As a user:
 
 ```shell
 mamba env create -f environment.yml
+mamba activate calliope-pathways
 ```
 
-As a developer:
+As a developer on WINDOWS:
 
 ```shell
 mamba create -n calliope-pathways-dev -c conda-forge/label/calliope_dev -c conda-forge --file requirements/base.txt --file requirements/dev.txt
 mamba activate calliope-pathways-dev
 pip install --no-deps -e .
 ```
+
+As a developer on UNIX:
+
+```shell
+mamba create -n calliope-pathways-dev -c conda-forge/label/calliope_dev -c conda-forge --file requirements/base.txt --file requirements/dev.txt
+mamba activate calliope-pathways-dev
+pip install --no-deps -e .
+```
+
+### Installing a solver
+
+We recommend you use Gurobi if you have access to a license, otherwise use CBC.
+
+To install CBC into your mamba environment on Windows:
+
+```shell
+mamba install curl
+curl -L https://github.com/coin-or/Cbc/releases/download/releases%2F2.10.10/Cbc-releases.2.10.10-w64-msvc17-md.zip -o cbc.zip
+unzip cbc.zip "bin/*" -d %CONDA_PREFIX%
+```
+
+To install CBC into your mamba environment on MacOS / Linux:
+
+```shell
+mamba install coin-or-cbc
+```

docs/examples/index.md

@@ -2,7 +2,7 @@
 
 In this section of the documentation, we will take you through some simple and more advanced topics related to building and running Calliope pathway optimisation models.
 
-The ["national scale" example][national-scale-example-model-pathway -ptimisation] builds a model for part of a national grid, exhibiting the following Calliope functionality:
+The ["national scale" example][national-scale-example-model-pathway-optimisation] builds a model for part of a national grid, exhibiting the following Calliope functionality:
 
 * Use of initial capacities.
 * Use of technology lifetimes that fall _between_ investment steps.

docs/examples/national_scale.py

@@ -16,7 +16,8 @@
 # %% [markdown]
 # # National scale example model pathway optimisation
 #
-# In this tutorial, we use the national scale example model to solve a pathway optimisation problem.
+# In this tutorial, we use the Calliope national scale example model to solve a pathway optimisation problem.
+# This model can be loaded in its non-pathway format within Calliope as `calliope.examples.national_scale()`.
 
 # %%
 

docs/hooks/generate_math_docs.py

@@ -92,10 +92,10 @@ def write_file(
     nav_reference = [
         idx
         for idx in config["nav"]
-        if isinstance(idx, dict) and set(idx.keys()) == {"Math documentation"}
+        if isinstance(idx, dict) and set(idx.keys()) == {"Math Documentation"}
     ][0]
 
-    nav_reference["Math documentation"].append(output_file.as_posix())
+    nav_reference["Math Documentation"].append(output_file.as_posix())
 
     math_doc = model.math_documentation.write(format="md", mkdocs_tabbed=True)
     file_to_download = Path("..") / filename

environment.yml

@@ -3,6 +3,6 @@ channels:
   - conda-forge
   - conda-forge/label/calliope_dev
 dependencies:
-  - calliope>=0.7.0dev
+  - calliope>=0.7.0dev3
   - pip:
     - "."

mkdocs.yml

@@ -34,6 +34,28 @@ plugins:
       include_source: True
       execute: true
       include_requirejs: true
+  - mkdocstrings:
+      default_handler: python
+      handlers:
+        python:
+          options:
+            show_bases: true
+            filters:
+              - "!^_"
+            heading_level: 1
+            show_root_heading: true
+            merge_init_into_class: true
+            show_if_no_docstring: true
+            signature_crossrefs: true
+            show_root_toc_entry: false
+            show_signature_annotations: false
+            inherited_members: true
+          paths: [src]
+          import:
+            - https://docs.python.org/3/objects.inv
+            - https://pandas.pydata.org/docs/objects.inv
+            - https://docs.xarray.dev/en/stable/objects.inv
+            - https://calliope.readthedocs.io/en/latest/objects.inv
 markdown_extensions:
   - admonition
   - attr_list

pyproject.toml

@@ -65,10 +65,10 @@ quiet-level = 3
 
 [tool.setuptools.packages.find]
 where = ["src"]
-include = ["calliope*"]
+include = ["calliope_pathways*"]
 
 [tool.setuptools.package-data]
-calliope = ["models/**/*", "math/*"]
+calliope_pathways = ["models/**/*", "math/*", "config/*"]
 
 [tool.setuptools]
 license-files = ["LICENSE"]

requirements/base.txt

@@ -1 +1 @@
-calliope>=0.7.0dev2
+calliope>=0.7.0dev3

src/calliope_pathways/math/new_param_schema.yaml → src/calliope_pathways/config/new_param_schema.yaml

@@ -47,16 +47,6 @@ techs:
       Sets `storage_cap` lower bound in first investment period during pathway optimisation.
     x-unit: energy.
 
-
-  storage_initial:
-    $ref: "#/$defs/TechParamNullNumber"
-    default: 0
-    x-type: float
-    title: Initial storage level.
-    description: >-
-      Set stored flow in device at the first timestep, as a fraction of total storage capacity.
-    x-unit: fraction.
-
   source_cap_initial:
     $ref: "#/$defs/TechParamNullNumber"
     default: 0

src/calliope_pathways/models.py

@@ -16,9 +16,9 @@
 from calliope.util import schema
 
 MODEL_DIR = Path(importlib.resources.files("calliope_pathways") / "models")
-MATH_DIR = Path(importlib.resources.files("calliope_pathways") / "math")
+CONFIG_DIR = Path(importlib.resources.files("calliope_pathways") / "config")
 
-new_schema = AttrDict.from_yaml(MATH_DIR / "new_param_schema.yaml")
+new_schema = AttrDict.from_yaml(CONFIG_DIR / "new_param_schema.yaml")
 
 for key, new_params in new_schema.items():
     schema.update_model_schema(key, new_params, allow_override=False)

src/calliope_pathways/models/national_scale/model.yaml

@@ -9,7 +9,7 @@ config:
     name: National-scale example model
     # What version of Calliope this model is intended for
     calliope_version: 0.7.0
-    custom_math: [../../math/pathways.yaml]
+    add_math: [../../math/pathways.yaml]
     time_resample: "24h"
 
   build:
@@ -27,6 +27,10 @@ parameters:
     dims: costs
   # `bigM` sets the scale of unmet demand, which cannot be too high, otherwise the optimisation will not converge
   bigM: 1e6
+  investstep_resolution:
+    data: 10
+    index: [2020, 2030, 2040, 2050]
+    dims: investsteps
 
 data_sources:
   csp_source: