Merge pull request #81 from KTH-dESA/packaging

Preparation of code for packaging. 
For creating a package, pending are modifications that allow running the package in a user defined directory instead of the location where the package is installed.

.github/workflows/testing.yaml

@@ -0,0 +1,34 @@
+name: Python
+
+on: [push, pull_request]
+
+jobs:
+  build:
+
+    runs-on: ${{ matrix.os }}
+    strategy:
+      matrix:
+        python-version: ["3.9", "3.10", "3.11"]
+        # os: [ubuntu-latest, windows-latest]
+        os: [ubuntu-latest]
+
+    steps:
+      - uses: actions/checkout@v3
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+          cache: pip 
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install hatch
+      - name: Create Environment 
+        run: hatch env create 
+      - name: Test OSeMOSYS_step
+        run: hatch run test
+      # - name: Format OSeMOSYS_step
+      #   run: hatch fmt
+      # uncomment for auto-pushing to PyPI
+      # - name: Build OSeMOSYS_step
+      #   run: hatch build

.gitignore

@@ -171,4 +171,4 @@ cython_debug/
 #.idea/
 
 # VS Code
-.vscode/
+.vscode/

README.md

@@ -1,10 +1,11 @@
 # OSeMOSYS step
-This repository contains a set of scripts to conduct model runs with limited 
+
+This repository contains a set of scripts to conduct model runs with limited
 foresight with OSeMOSYS models.
 
-# Directory Structure 
+# Directory Structure
 
-Before the workflow has been ran, the directory will look like what is shown below: 
+Before the workflow has been run, the directory will look like what is shown below:
 
 ```bash
 OSeMOSYS_STEP
@@ -34,19 +35,19 @@ OSeMOSYS_STEP
 ```
 
 ## `data`
-The `data/` directory holds information on the reference model, and each 
-scenario you want to run. All scenario information must be nested under a 
+The `data/` directory holds information on the reference model, and each
+scenario you want to run. All scenario information must be nested under a
 `scenarios/` subdirectory.
 
 ### `data/scenarios`
-The `data/scenarios` subdirectory holds information on the options (or decisions) 
-that the model can make. Within this directory, numerically ordered subdirectories 
-are created to hold information on each step. For example, if there are 5 steps 
-in the model run, there will be 5 subdirectories, each labeled 0 through 4. 
+The `data/scenarios` subdirectory holds information on the options (or decisions)
+that the model can make. Within this directory, numerically ordered subdirectories
+are created to hold information on each step. For example, if there are 5 steps
+in the model run, there will be 5 subdirectories, each labeled 0 through 4.
 
-Within each `data/scenarios/#` subdirectory, CSV files hold information 
-on the options that can be made. Each CSV file must follow the formatting 
-shown below. 
+Within each `data/scenarios/#` subdirectory, CSV files hold information
+on the options that can be made. Each CSV file must follow the formatting
+shown below.
 
 |             PARAMETER            | REGION | TECHNOLOGY | OPTION | YEAR | VALUE     |
 |:--------------------------------:|:------:|------------|--------|:----:|-----------|
@@ -61,45 +62,45 @@ shown below.
 | TotalAnnualMaxCapacityInvestment | UTOPIA | COAL       | 1      | 2049 | 0         |
 | TotalAnnualMaxCapacityInvestment | UTOPIA | COAL       | 1      | 2050 | 0         |
 
-Note, that the `OPTION` column will dictate whether the option is made or not. For each 
-model run, either all data identifed as the `0` option or the `1` option will be used, 
-not both. There can be as many options as the modeller desires. 
+Note, that the `OPTION` column will dictate whether the option is made or not. For each
+model run, either all data identifed as the `0` option or the `1` option will be used,
+not both. There can be as many options as the modeller desires.
 
 ## `model`
 
 This directory houses the reference GNU MathProg OSeMOSYS model you are using
 
 ## `results`
 
-Contains CSV result files for each model run 
+Contains CSV result files for each model run
 
 ## `src`
 
-Contains all scripts 
+Contains all scripts
 
 ## `steps`
 
 Solver outputs for each CSV model run. If using GLPK, these will be result CSV
-files, if using a different solver, this will be a text file. 
+files, if using a different solver, this will be a text file.
 
-# Running Instructions 
+# Running Instructions
 
 ## Objective
-Run a 5 step model, over the horizon of 1990 to 2010 that makes investment decesions 
+Run a 5 step model, over the horizon of 1990 to 2010 that makes investment decesions
 about allowing investment in coal.
 
-## 1. Add the model file 
+## 1. Add the model file
 Drop in an osemsosys file (called `osemosys.txt`) into the `model/` directory
 
 ## 2. Add the base data file
 **NB:** Neither the model data nor the scenario data should make use of the parameter _TotalAnnualMaxCapacity_. It can cause problems when passing _NewCapacity_ from one step to the next step.
 
-Drop in a MathProg formatted data file in the `data/` folder. The data file 
+Drop in a MathProg formatted data file in the `data/` folder. The data file
 can be long formatted (otoole) or wide formatted (momani)
 
-## 3. Add in scenario data 
+## 3. Add in scenario data
 For the first step, add the file `data/scenarios/1/A.csv`, where one
-option allows investment in IMPHCO, and one options does not allow it. 
+option allows investment in IMPHCO, and one options does not allow it.
 
 |             PARAMETER            | REGION | TECHNOLOGY | OPTION | YEAR | VALUE     |
 |:--------------------------------:|:------:|------------|--------|:----:|-----------|
@@ -114,8 +115,8 @@ option allows investment in IMPHCO, and one options does not allow it.
 | TotalAnnualMaxCapacityInvestment | UTOPIA | IMPHCO1    | 1      | 2009 | 0         |
 | TotalAnnualMaxCapacityInvestment | UTOPIA | IMPHCO1    | 1      | 2010 | 0         |
 
-In this same step, but independent from the decision to invest in IMPHCO, we 
-want to also add the option to invest in importing uranium. Add the file 
+In this same step, but independent from the decision to invest in IMPHCO, we
+want to also add the option to invest in importing uranium. Add the file
 `data/scenarios/1/B.csv`
 
 |             PARAMETER            | REGION | TECHNOLOGY | OPTION | YEAR | VALUE     |
@@ -131,8 +132,8 @@ want to also add the option to invest in importing uranium. Add the file
 | TotalAnnualMaxCapacityInvestment | UTOPIA | IMPURN1    | 1      | 2009 | 0         |
 | TotalAnnualMaxCapacityInvestment | UTOPIA | IMPURN1    | 1      | 2010 | 0         |
 
-In the second step, through one decesion, we want to decide the allowable investment 
-in importing coal, importing RL1, and if RLu is allowed to run or not. Add the file 
+In the second step, through one decesion, we want to decide the allowable investment
+in importing coal, importing RL1, and if RLu is allowed to run or not. Add the file
 `data/scenarios/2/C.csv`
 
 |             PARAMETER                   | REGION | TECHNOLOGY | OPTION | YEAR | VALUE     |
@@ -168,20 +169,20 @@ in importing coal, importing RL1, and if RLu is allowed to run or not. Add the f
 | TotalTechnologyAnnualActivityUpperLimit | UTOPIA | RLu        | 1      | 2009 | 0         |
 | TotalTechnologyAnnualActivityUpperLimit | UTOPIA | RLu        | 1      | 2010 | 0         |
 
-## 4. Run the workflow 
-```bash 
+## 4. Run the workflow
+```bash
 cd src
-python main_ms.py --step_length 5 --input_data ../data/<datafile_name>.txt 
+python main_ms.py --step_length 5 --input_data ../data/<datafile_name>.txt
 ```
 
 ## 6. View Results
-Under the results folder, there should now be results for all the 
-permutations of options. 
+Under the results folder, there should now be results for all the
+permutations of options.
 
-For example, the results of implementing option 0 in scenario A, option 1 in 
+For example, the results of implementing option 0 in scenario A, option 1 in
 scenario B, and option 1 in scenario C are nested under the folder `results/1A0-1B1/2C1`.
 
-```bash 
+```bash
 OSeMOSYS_STEP
 ├── data
 ├── model
@@ -217,3 +218,53 @@ OSeMOSYS_STEP
 ├── src
 └── steps
 ```
+
+# Installation
+
+You can use pip to install the package directly from Github:
+
+    pip install git+https://github.com/KTH-dESA/OSeMOSYS_step.git@main#egg=osemosys_step
+
+While in development phase, you can test this like so:
+
+    pip install --dry-run git+https://github.com/KTH-dESA/OSeMOSYS_step.git@packaging#egg=osemosys_step
+
+Or you install a development version like so:
+
+    git clone https://github.com/KTH-dESA/OSeMOSYS_step.git osemosys_step
+    cd osemosys_step
+    pip install -e .
+
+# Development
+
+OSeMOSYS_step is packaged using [hatchling](https://hatch.pypa.io/latest/)
+
+Create the development environment:
+
+    hatch env create
+
+Run the tests:
+
+    hatch run test
+
+Run linting for style, typing and format:
+
+    hatch fmt
+
+The version number is taken from the git tag.  Before building and publishing the package, you should create a new annotated tag.
+
+First, check the previous tags:
+
+    git tag
+
+Then create a new annotated tag:
+
+    git tag -a v1.0 -m "First full release of OSeMOSYS Step"
+
+Build the package:
+
+    hatch build
+
+Publish the package to PyPI:
+
+    hatch publish