project-pareto

An Optimization Framework for Produced Water Management and Beneficial Reuse

Getting started

Creating a Conda environment

The recommended way to install Pareto is to use a Conda environment.

A Conda environment is a separate installation directory where packages and even different Python versions can be installed without conflicting with other Python versions installed on the system, or other environments.

To create a Conda environment, the conda command should be installed and configured for your operating system. Detailed steps to install and configure conda are available here.

For users

Create a Conda environment:

conda create -n pareto-env python=3.8 pip --yes
conda activate pareto-env

Install the latest version from the repository's main branch:

pip install 'project_pareto @ https://github.com/project-pareto/project-pareto/archive/main.zip`

Install the open-source solvers packaged by the IDAES project:

idaes get-extensions --verbose

Open a Python shell and test that the pareto package was installed correctly:

python
>>> import pareto

For developers

(Recommended) Create a dedicated Conda environment for development work:

conda create -n pareto-dev python=3.8 pip --yes
conda activate pareto-dev

Clone the repository and enter the project-pareto directory:

git clone https://github.com/project-pareto/project-pareto
cd project-pareto

Install the Python package using pip and the requirements-dev.txt file:

pip install -r requirements-dev.txt

Install the pre-commit checks that will run automatically whenever git commit is used, preventing the commit from being created if any of the checks fail:

pre-commit install

Install the open-source solvers packaged by the IDAES project:

idaes get-extensions --verbose

To test that the installation was successful, run the test suite using the pytest command:

pytest --verbose

Notes for developers

Editable installation with pip

The developer installation will install the Python packages and modules found in the cloned directory in editable mode (as opposed to the default behavior of installing a copy of it), which means that any modification made to the code in the cloned directory (including switching to a different branch with git switch/git checkout, or updating the directory with git pull) will be available when using the package in Python, regardless of e.g. the current working directory.

Formatting code with Black

Black (https://black.readthedocs.io) is the code formatter used by Pareto to ensure that the codebase is formatted consistently.

Installation

Black is part of the Pareto developer dependencies and it is installed alongside the other dependencies when running pip install -r requirements-dev.txt in the Conda environment used for development.

To verify that Black is installed correctly, run e.g.:

black --version

Usage

Before committing code to the Pareto repository, run black locally (i.e. on your development machine) with the default options from the repository root:

black .

Automated check

When a PR is created or updated, as part of the automated check suite running on GitHub, Black will run in "check mode": rather than formatting files, it will check if any file would need to be formatted, and exiting with an error if this is the case.

To reproduce this check locally (e.g. to verify that your code would pass this check when enforced on the GitHub side), from the root of the repository, run:

black --check .

NOTE: This is now done automatically as part of the pre-commit checks (see above).

Funding Acknowledgement

This work was conducted as part of the Produced Water Optimization Initiative, “Project PARETO”, with support through the Natural Gas & Oil Program within the U.S. Department of Energy’s Office of Fossil Energy and Carbon Management (FECM). For more information please see www.project-pareto.org.