Element Finance market simulation and analysis

This project is a work-in-progress. All code is provided as is and without guarantee. Documentation can be found here.

Install

Set up your favorite python virutal environment with python == 3.8 (we recommend pyenv and virtualenv). While we don't explicitly support python > 3.8, we haven't had trouble running on later versions (with one exception noted below). For example:

pyenv install 3.8.16
pyenv local 3.8.16
python -m venv elf-env
source elf-env/bin/activate

Once this is done, check that your version is correct when you run python --version. Within the virtualenv, upgrade pip with python -m pip install --upgrade pip and then install the required packages.

python -m pip install -r requirements.txt

for Python 3.11, an extra step is required because of the stochastic package dependency:

python -m pip install stochastic --ignore-requires-python
python -m pip install -r requirements.txt

If you intend to improve the documentation, then you must also install the packages in requirements-dev.txt.

Finally, install the elfpy package with python -m pip install -e . from the git directory root.

Docker

To install a docker development environment which may be more reliable to install project dependencies:

docker build -t elf-simulations-dev .

Then to create an isolated shell environment which observes file changes run:

docker run -it --name elf-simulations-dev --rm --volume $(pwd):/app/ --net=host elf-simulations-dev:latest bash

Testing

Testing is achieved with py.test. You can run all tests from the repository root directory by runing python -m pytest, or you can pick a specific test in the tests/ folder with python -m pytest tests/{test_file.py}.

Examples

Python files in the examples/ folder should be executable from the repository root. Run them with the -h flag to see argument options. The Jupyter notebooks contained in examples/notebooks/ should be run locally using Jupyter, VS Code, or something equivalent. We do not recommend using Google Colab because the install process requires upgrading the Colab Python version to 3.10 and pip installing elfpy from the git URI.

Contributor git workflow:

We will follow the Rebase workflow that is also used by the Element frontend team. Commits to main should only be made in the form of squash merges from pull requests. For example,

git checkout feature-branch
git add [files to be committed]
git commit -m 'Complete change summary'

later, some new commits show up in main, so we rebase our branch

git pull --rebase origin main
git push feature-branch

now, we have completed our feature, so we create a PR to merge the branch into main

Once the PR is approved, we perform a final rebase, if necessary, and then a squash merge. This means each PR results in a single commit to main.