Skip to content

Commit

Permalink
Merge pull request #184 from OSeMOSYS/install-update
Browse files Browse the repository at this point in the history 
Update Install Steps and Env File
  • Loading branch information
@trevorb1
trevorb1 authored Jun 17, 2024
2 parents 250e57d + 632d6a8 commit 21a2394
Show file tree
Hide file tree
Showing 5 changed files with 107 additions and 128 deletions.
3 changes: 0 additions & 3 deletions .gitmodules
View file
Original file line number Diff line number Diff line change
@@ -1,3 +0,0 @@
[submodule "OSeMOSYS_GNU_MathProg"]
path = resources/OSeMOSYS_GNU_MathProg
url = https://github.com/OSeMOSYS/OSeMOSYS_GNU_MathProg
2 changes: 1 addition & 1 deletion docs/contributing.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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
:::

Expand Down
221 changes: 100 additions & 121 deletions docs/installation.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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 [email protected]: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
Expand All @@ -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
Expand All @@ -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
Expand All @@ -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.
Expand All @@ -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"
Expand All @@ -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.
Expand All @@ -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.
Expand All @@ -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/)
Expand Down
8 changes: 5 additions & 3 deletions docs/requirements.txt
View file
Original file line number Diff line number Diff line change
@@ -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
docutils==0.17.1
sphinx_book_theme
1 change: 1 addition & 0 deletions workflow/envs/osemosys-global.yaml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -19,6 +19,7 @@ dependencies:
- cartopy>=0.23
- geopandas>=0.14
- plotly>=5.22
- glpk>=5.0

- pip:
- world-bank-data>=0.1.3
Expand Down

0 comments on commit 21a2394

Please sign in to comment.