diff --git a/.gitmodules b/.gitmodules index 16e91504..e69de29b 100644 --- a/.gitmodules +++ b/.gitmodules @@ -1,3 +0,0 @@ -[submodule "OSeMOSYS_GNU_MathProg"] - path = resources/OSeMOSYS_GNU_MathProg - url = https://github.com/OSeMOSYS/OSeMOSYS_GNU_MathProg diff --git a/docs/contributing.md b/docs/contributing.md index 9a51a166..e2b13028 100644 --- a/docs/contributing.md +++ b/docs/contributing.md @@ -186,7 +186,7 @@ to avoid any problems with your installed Python packages. This can easily be done via [Miniconda](https://docs.conda.io/en/latest/miniconda.html): :::{seealso} -How to [install](installation.md#5-create-the-conda-environment) OSeMOSYS +How to [install](installation.md#3-create-the-conda-environment) OSeMOSYS Global's prepared conda environment ::: diff --git a/docs/installation.md b/docs/installation.md index 6375aefc..e388f99f 100644 --- a/docs/installation.md +++ b/docs/installation.md @@ -12,43 +12,110 @@ Windows, we suggest you install ## Installation Steps -### 1. Install GLPK +### 1. Clone Repository -The GNU GLPK package is a open-source linear programming package. OSeMOSYS -Global uses it to create a linear programming file. Full installation -instructions can be found on their [website](https://www.gnu.org/software/glpk/). -Once installed run the command `glpsol` in the command line. The following -message will display indicating that GLPK has installed correctly. +All source code for OSeMOSYS Global is hosted in a +[GitHub repository](https://github.com/OSeMOSYS/osemosys_global), nested under +the [OSeMOSYS organization](https://github.com/OSeMOSYS). -``` bash -$ glpsol +To clone by `HTTPS`, run the following command. -GLPSOL: GLPK LP/MIP Solver, v4.65 -No input problem file specified; try glpsol --help +```bash +$ git clone https://github.com/OSeMOSYS/osemosys_global.git ``` -### 2. Install a Solver +To clone by `SSH`, run the following command. Note, you will first need to +set up a `SSH` key following [instructions by GitHub](https://docs.github.com/en/authentication/connecting-to-github-with-ssh/adding-a-new-ssh-key-to-your-github-account). + +```bash +git clone git@github.com:OSeMOSYS/osemosys_global.git +``` + +:::{seealso} +If you are new to [Git](https://git-scm.com) and [GitHub](https://github.com/), +not to worry! All relevant Git commands are provided below. However, if you +would like to learn more about version control, GitHub has great +[documentation](https://docs.github.com/en/get-started/quickstart/hello-world). +::: + + +### 2. Install Mamba -OSeMOSYS Global supports three solvers. Included is the open-source solver -[CBC](https://github.com/coin-or/Cbc), and the commercial solvers -[Gurobi](https://www.gurobi.com/) and -[CPLEX](https://www.ibm.com/analytics/cplex-optimizer). **You must install at -least one of these solvers**. If you are uncertain about which one, we suggest -[CBC](https://github.com/coin-or/Cbc) as it is free and the easiest to setup. +OSeMOSYS Global uses Python and the workflow management tool [Snakemake](https://snakemake.readthedocs.io) to build OSeMOSYS models. To manage the Python dependencies, we recommend using [mamba](https://mamba.readthedocs.io/). Installation instructions to install mamba through miniforge can be found on the mamba website [here](https://mamba.readthedocs.io/en/latest/installation/mamba-installation.html). + +To verify that mamba is installed, run the command `mamba info`. Information +about your mamba environment will be printed out. + +```bash +(base) ~/ $ mamba info + + active environment : base + active env location : /home/xxx/miniforge3 + shell level : 3 + user config file : /home/xxx/.condarc + populated config files : /home/xxx/miniforge3/.condarc + conda version : 24.3.0 + conda-build version : not installed + python version : 3.10.14.final.0 +... +``` :::{note} -Support for the new open-source solver, [HiGHS](https://highs.dev/), is planned for a later release. +You may need to restart your terminal for mamba to finish installing. Once +Miniconda is installed, you will see `(base)` in front at the start of your +command line. ::: -#### 2.1. Install CBC +### 3. Create the Conda Environment + +OSeMOSYS Global stores all project dependencies in a file that mamba can read +to create a new environment. Run the command below to create a new +envirnoment called `osemosys-global`. + +```bash +(base) ~/ $ mamba env create -f workflow/envs/osemosys-global.yaml +``` + +Once installed, activate the new `osemosys-global` environment. You will now see +`(osemosys-global)` at the start of your command prompt. + +```bash +(base) ~/ $ mamba activate osemosys-global +(osemosys-global) ~/ $ +``` + +### 4. (Optional) Install a Solver + +OSeMOSYS Global supports three solvers; [CBC](https://github.com/coin-or/Cbc), [Gurobi](https://www.gurobi.com/) and [CPLEX](https://www.ibm.com/analytics/cplex-optimizer). Moreover, OSeMOSYS uses [GLPK](https://www.gnu.org/software/glpk/) to generate solver independent linear programming file. **If you installed the dependencies through the environment file, and are using open-source solvers, you do not need to follow these steps.** + +#### 4.1. Install GLPK -Follow the [download instruction](https://github.com/coin-or/Cbc#download) on -CBC's GitHub. Once installed, run the command `cbc` in the command line. The -following message will display indicating that CBC has installed correctly. +[GNU GLPK](https://www.gnu.org/software/glpk/) is an open-source linear programming +package that **will be installed with the environment**. OSeMOSYS Global uses +it to create a linear programming files. To check that +it installed correctly, run the command `glpsol` in the command line. The +following message will display indicating that GLPK has installed. + +```bash + ~/ $ glpsol + +GLPSOL: GLPK LP/MIP Solver, v4.65 +No input problem file specified; try glpsol --help +``` + +If for any reason you need to manually install GLPK, you can do so through mamba +using the command `mamba install glpk`. + +#### 4.2. Install CBC + +[CBC](https://github.com/coin-or/Cbc) is open-source and +**will be installed with the environment**. To check that +it installed correctly, run the command `cbc` in the command line. The +following message will display indicating that CBC has installed. Type `quit` to exit CBC. ```bash -$ cbc +(osemosys-global) ~/ $ cbc Welcome to the CBC MILP Solver Version: 2.10.3 @@ -59,7 +126,11 @@ Enter ? for list of commands or help Coin: ``` -#### 2.2. Install CPLEX +If a differnt CBC version needs to be installed, follow the +[download instruction](https://github.com/coin-or/Cbc#download) on +CBC's GitHub. + +#### 4.3. Install CPLEX If you are an academic researcher or student, you may qualify for the [academic license](https://www.ibm.com/academic/topic/data-science) of IBM's @@ -70,7 +141,7 @@ message will display indicating that CPLEX has installed correctly. Type `quit` to exit CPLEX. ```bash -$ cplex + ~/ $ cplex Welcome to IBM(R) ILOG(R) CPLEX(R) Interactive Optimizer 22.1.0.0 with Simplex, Mixed Integer & Barrier Optimizers @@ -84,7 +155,7 @@ information on commands. CPLEX> ``` -#### 2.3. Gurobi +#### 4.4. Gurobi If you are an academic researcher or student, you may qualify for the [academic license](https://www.gurobi.com/academia/) of Gurobi's optimizer. @@ -94,8 +165,7 @@ Once installed, run the command `gurobi_cl` in the command line. The following message will display indicating that Gurobi has installed correctly. ```bash - -$ gurobi_cl + ~/ $ gurobi_cl Set parameter Username Set parameter LogFile to value "gurobi.log" @@ -105,94 +175,7 @@ Usage: gurobi_cl [--command]* [param=value]* filename Type 'gurobi_cl --help' for more information. ``` -### 3. Clone Repository - -All source code for OSeMOSYS Global is hosted in a -[GitHub repository](https://github.com/OSeMOSYS/osemosys_global), nested under -the [OSeMOSYS organization](https://github.com/OSeMOSYS). - -:::{seealso} -If you are new to [Git](https://git-scm.com) and [GitHub](https://github.com/), -not to worry! All relevant Git commands are provided below. However, if you -would like to learn more about version control, GitHub has great -[documentation](https://docs.github.com/en/get-started/quickstart/hello-world). -::: - -In the command line, navigate to the directory you want to clone the repository -into. Clone the repository using the command below, being sure to include the -`--recurse-submodules` flag. Navigate into the new `osemosys_global` directory. - -```bash -$ git clone --recurse-submodules https://github.com/OSeMOSYS/osemosys_global.git - -$ cd osemosys_global - -~/osemosys_global$ - -``` - -:::{note} -If the repository was cloned without the `--recurse-submodules` flag, run the -commands `git submodule init` and `git submodule update ` - -```bash -~/osemosys_global$ git submodule init -~/osemosys_global$ git submodule update -``` -::: - -### 4. Install Miniconda - -OSeMOSYS Global processes and plots data using a series of Python scripts. -OSeMOSYS Global uses [Miniconda](https://docs.conda.io/en/latest/miniconda.html) -to helps manage all required Python packages. Install Miniconda following their -[instructions](https://docs.conda.io/en/latest/miniconda.html). - -To verify that conda is installed, run the command `conda info`. Information -about your conda environment will be printed out. - -```bash -(base) ~/osemosys_global$ conda info - -active environment : base -active env location : ~/miniconda3/envs/base -shell level : 2 -user config file : ~/.condarc -populated config files : -conda version : 4.12.0 -... -``` -:::{note} -You may need to restart your terminal for conda to finish installing. Once -Miniconda is installed, you will see `(base)` in front at the start of your -command line. -::: - -### 5. Create the Conda Environment - -OSeMOSYS Global stores all project dependencies in a file that conda can read -to create a new environment. Run the command below to create a new -envirnoment called `osemosys-global`. - -```bash -(base) ~/osemosys_global$ conda env create -f workflow/envs/osemosys-global.yaml -``` - -Once installed, activate the new `osemosys-global` environment. You will now see -`(osemosys-global)` at the start of your command prompt. - -```bash -(base) ~/osemosys_global$ conda activate osemosys-global -(osemosys-global) ~/osemosys_global$ -``` - -:::{note} -The installation of the `osemosys-global` environment may take a few minutes (up to 30min). -This is normal. If you are proficient with conda, installing all dependencies manually -can be quicker. -::: - -### 6. Run a Model +### 5. Run a Model And thats it! You can now follow [our examples](getting-started.md#examples) to create a model for yourself. @@ -206,10 +189,6 @@ our GitHub [discussion fourm](https://github.com/OSeMOSYS/osemosys_global/discussions) is a great place to ask general OSeMOSYS Global questions. -:::{seealso} - OSeMOSYS' [Google Group](https://groups.google.com/g/osemosys) is a good place to ask questions about the OSeMOSYS framework. -::: - ## Dependencies OSeMOSYS Global relies on numerous open-source community supported tools. @@ -219,7 +198,7 @@ investigate further! [Python](https://www.python.org/downloads/) : All data processing is writen in the Python programming language -[Miniconda](https://docs.conda.io/en/latest/miniconda.html) +[Mamba](https://mamba.readthedocs.io/en/) : Python package management tool [Snakemake](https://snakemake.readthedocs.io/en/stable/) diff --git a/docs/requirements.txt b/docs/requirements.txt index 8ce4b824..d1c01a2f 100644 --- a/docs/requirements.txt +++ b/docs/requirements.txt @@ -1,24 +1,26 @@ # Requirements file for ReadTheDocs, check .readthedocs.yml. # To build the module reference correctly, make sure every external package # under `install_requires` in `setup.cfg` is also listed here! + +# scripts importlib-metadata seaborn +pandas>=2.0 geopandas urllib3 PyYAML pytest world-bank-data scikit-learn -myst-parser otoole>=1.1.0 scipy dash geos cartopy -pandas>=2.0 # docs sphinx myst-parser pydata-sphinx-theme>=0.8.1 -docutils==0.17.1 \ No newline at end of file +docutils==0.17.1 +sphinx_book_theme \ No newline at end of file diff --git a/workflow/envs/osemosys-global.yaml b/workflow/envs/osemosys-global.yaml index 4f66048a..12d347d2 100644 --- a/workflow/envs/osemosys-global.yaml +++ b/workflow/envs/osemosys-global.yaml @@ -19,6 +19,7 @@ dependencies: - cartopy>=0.23 - geopandas>=0.14 - plotly>=5.22 + - glpk>=5.0 - pip: - world-bank-data>=0.1.3