EvoSim

Simulation package for the EVOLVE project: Electric Vehicle fleet Optimisation for lowering vehicle Emissions.

Installation for users

The latest package can be installed with:

pip install git+https://github.com/ImperialCollegeLondon/EvoSim.git@main

Specific versions or branches (e.g. "develop") can be installed by replacing "main" with the name of the commit, tag, or branch.

The only pre-requisite is python 3.8 or higher and git.

Installation for Developers

Initial setup

The pre-requisite for development are python 3.8 or higher, the python package manager poetry, git, as well as pandoc to create parts of the documentation.

EvoSim can be installed for development with:

# Clone the repository
git clone https://github.com/ImperialCollegeLondon/EvoSim
# Move to the directory with the source files
cd EvoSim
# Switch to a new branch
git switch -c my_new_branch origin/develop
# Install a virtual environment with the EvoSim package
poetry install
# Start hacking!!

In rare cases Poetry may not be able to install or update all dependencies required. If this happens, simply install any failed attemps with:

python -m pip install SomePackage 

All development should occur in a branch starting from "develop". It should be merged back into the development branch "develop" via a pull-request.

It is recommended to use pre-commit. It will run a number of tests before each commit to help maintain code quality. For instance, it will run black to ensure the code is formatted in a consistent manner. To enable pre-commit on your worktree, first install it, then run:

pre-commit install

Testing

EvoSim is developed using the Test Driven Development methodology. In practice, it means many test have been written ensuring that each part of the code works as expected. There are two types of tests:

• unittest: in the "tests/" subdirectory. They check the internal implementation of EvoSim.

  poetry run pytest

• doctest: in the "*.rst" files with the source code. These tests are part of the documentation and document how EvoSim can be used and enhanced by developers.

  poetry run sphinx-build -E -b doctest docs build

Linux, MacOS, and Window Linux Subsystem users can run both types of tests with:

make tests

Documentation

The documentation can be generated with:

poetry run sphinx-build -b html docs build

Then open the file "build/index.html" with a browser. Note that is necessary to install pandoc to convert the how-to notebooks which are part of the documentation.

Preparing a new release

Once it is time for a new release, run the following steps:

1. create a new branch:

   git fetch origin
   git switch -c release_XXX origin/develop

2. bump the version up

   poetry run bump2version minor

3. open a pull request against "develop" and merge

4. open a pull request from "develop" to "main" and merge

5. release via github