diff --git a/README.md b/README.md index 286a3da..8e8e579 100644 --- a/README.md +++ b/README.md @@ -1,8 +1,12 @@ # echo (energy and commodity holistic optimiser) +`echo` is a python-based multi-commodity energy system optimisation tool designed to answer grid integration questions. + +This project is developed and maintained by the [Centre for Energy Systems](https://energysystems.anu.edu.au/) at the Australian National University. + ## Installation -This package requires that you have python 3.7+ installed and it is recommended you use a virtual environment. +`echo` requires requires python 3.11-3.14. To install this package you need to: @@ -12,25 +16,40 @@ To install this package you need to: 2. Change to the echo directory: `cd echo` -3. Install using uv (recommended): +3. Install using `uv` (recommended): + `uv sync --python 3.13 --all-extras` - or pip: + + or `pip`: + `pip install --group all` -NOTE: This package is not on pypi - `pip install echo` will NOT install this package. It will install a different package with the same name. +NOTE: This package is not on pypi - **`pip install echo` will NOT install this package**. It will install a different package with the same name. ## Solver -The following solvers can be used +Different solvers can be used within echo. Solvers are installed separately; see below for links to install instructions. + +There are three prerequisites to using a solver in `echo`: -Free for academic use only: +1. The solver must be installed. +2. The solver's executable must be in the `PATH` or equivalent. For example: + `PATH="/opt/cplex:$PATH` + in `~/.bashrc` for linux systems using bash. +3. `echo` needs to know which solver to use. There are two ways of doing this: -- CPLEX (recommended): This has been tested the most. It requires a license but is free for academic users. To install, follow instructions [here](https://www.ibm.com/products/ilog-cplex-optimization-studio). After installing CPLEX you will need to add the binaries to your system path. -- GUROBI: Minimal testing: It requires a license but is free for academic users. Check their website for installation [instructions](https://www.gurobi.com/documentation/9.5/remoteservices/linux_installation.html). +- Exporting the `OPTIMISER_ENGINE` environment variable, eg. `export OPTIMISER_ENGINE=cplex` in a terminal. Defaults to `cplex`. +- Setting `echo.models.scenario.EngineSettings.engine`. Defaults to `"cplex"` -Open source: +The following solvers can be used. -- CBC: This solver can be used provided you only include linear costs (no quadratic costs or regularisation). Information on the solver is available [here](https://github.com/coin-or/Cbc). For installing on ubuntu run `sudo apt-get install -y coinor-cbc` +| Solver | Testing Status | License | Installation | Known as in `echo` | +| ------ | --------------- | ---------------------------------------------- | ------------------------------------------------------------------------------------------------------ | ------------------ | +| CPLEX | Most tested | Commercial, free for academic use with licence | [All OSs](https://www.ibm.com/products/ilog-cplex-optimization-studio) | cplex | +| GUROBI | Minimal testing | Commercial, free for academic use with licence | [Linux](https:/./www.gurobi.com/documentation/9.5/remoteservices/linux_installation.html) | gurobi | +| CBC | Minimal testing | Open source | [All OSs](https://github.com/coin-or/cbc#download) | cbc | +| GLPK | No testing | Open source | [Linux](https://www.gnu.org/software/glpk/#TOCdownloading) | glpk | +| Xpress | No testing | Commercial, free for academic use with licence | [All OSs](https://www.fico.com/fico-xpress-optimization/docs/latest/installguide/dhtml/chapinst1.html) | xpress | ## Documentation