<p align="center"> <img src="https://github.com/simonom/PyCHAM/blob/master/PyCHAM/PyCHAM_logo_transparent.pdf"/> </p>

Welcome to the PyCHAM (CHemistry with Aerosol Microphysics in Python Box Model) software for modelling of indoor environments, including aerosol chambers. Funding has been provided by the EUROCHAMP-2020 research project and the National Centre for Atmospheric Science (NCAS). Please open an issue on the GitHub repository or contact Simon O'Meara (simon.omeara@manchester.ac.uk) with any issues, comments or suggestions.

PyCHAM is an open-source computer code (written in Python) for simulating aerosol chambers. It is supplied under the GNU General Public License v3.0. The license document is provided with the software (LICENSE) and contains information around modification and conveyancing.

PyCHAM was written by Simon P. O'Meara, Shuxuan Xu and Ademipo Onanuga.

Table of Content

1. Documentation
2. Installation
3. Running
4. Testing
5. Inputs
6. Outputs
7. Photochemistry
8. Gas-particle Partitioning
9. Numerical Considerations
10. Quick Plotting Tab
11. Flow Mode
12. Indoor Air Quality Modelling
13. Major Version Updates
14. Ambient Modelling
15. Frequently Asked Questions
16. Acknowledgements

Documentation

The README file you are now viewing serves as the PyCHAM manual, explaining how to setup the software and use it. As an additional resource, we also provide an introductory video.

The article published in the Journal for Open Source Software explains the underlying mechanisms of PyCHAM and its purpose. This article was reviewed using v0.2.4 of PyCHAM. Additionally, the article published in Geophysical Model Development provides a detailed introduction of PyCHAM and its use. This article was reviewed using v2.1.1 of PyCHAM. The DOI for all PyCHAM versions is: 10.5281/zenodo.3752676.

Version numbers of PyCHAM try to adhere to the semantic described by semver, which is: MAJOR.MINOR.PATCH.

Installation

There are two options for installing, via conda and via pip. The pip method takes longer as the openbabel package has to be installed separately. The instructions below for the pip method currently apply only to linux and macOS, whilst the conda instructions apply to windows, linux and macOS.

Install via conda

1. Download the PyCHAM repository from github.com/simonom/PyCHAM

2. Download and install the package manager Miniconda (Anaconda is also suitable but takes more memory and takes longer to install) using the following address and selecting the appropriate operating system version: https://docs.conda.io/en/latest/miniconda.html.

3. Ensure conda is operating correctly, the method varies between operating systems and is explained here

The following steps are at the command line:

4. cd into the directory where the PyCHAM package is stored.

5. Use the following command to install: conda env create -f PyCHAM_OSenv.yml -n PyCHAMenv, where OS is replaced by your operating system name (win (for Windows), lin (for Linux), mac (for macOS)).

6. Activate the environment with the command: conda activate PyCHAMenv

7. For Windows and Mac, now also install openbabel using the following at the command line: conda install conda-forge::openbabel.

7a. In addition, it has been noted that when following the above steps in Windows, openbabel does not always link to its data directory. You can test this by looking for open babel warning messages when running the PyCHAM examples (to run PyCHAM please see Running). A message such as 'the aromatic.txt file could not be found' indicates the data library is not set. To set, search for Control Panel in the Windows search bar then User Accounts and User Accounts again. Then select 'Change my environment variables'. Then, under User variables, select New. Then create the new variable with Variable name 'BABEL_DATADIR' and with Variable value set as the path to the relevant open babel data directory. To identify your open babel data directory you should look for the open babel folder containing aromatic.txt at a location such as: C:\Users\your_account_name\.conda\pkgs\openbabel-2.4.1-py37_5\share\openbabel. Once the path is suppled to the Variable value box select OK to create the variable then open a new anaconda prompt to restart PyCHAM.

6b. On Mac (please skip this step if on Linux or Windows) it has been noted that when following the above steps and then running PyCHAM (to run PyCHAM please see Running), an error is given stating that Developer Tools have not been installed. If this error displays please follow the on-screen instructions to install Developer Tools.

7. Install is complete for Linux, Mac and Windows; to run PyCHAM please see Running.

Install via pip

1. Ensure that swig is installed on your system. For example, for macOS, a command at the command line like: brew install swig , and for linux a command at the command line like: sudo apt install swig

2. Ensure that eigen is available on your system. For example, for macOS, a command at the command line like: brew install eigen, and for linux, download the latest stable eigen release here, then unzip and move the unzipped folder into the /usr/local/include folder using a command at the command line like: sudo mv eigen-3.3.9 /usr/local/include

3. Create a virtual environment in a suitable location running with at least python3.6. For example, if your command line recognises python3.6 as python3.6, the command to make a virtual environment called 3env on macOS is: python3.6 -m venv 3env. Note that python3.6 in this example should be replaced with the appropriate command for recognising python on your machine (often just python).

4. Activate this environment. For example, for a virtual environment called 3env on macOS and linux the command at the command line is: source 3env/bin/activate. For example, for a virtual environment called 3env on Windows the command at the command line is: .\3env\Scripts\activate

5. openbabel must be installed separately to PyCHAM, begin by downloading and unzipping the tar file (file name containing .tar.) for the latest version of openbabel on github. Note that the unzipped version can be stored in the Downloads folder for the installation process.

The following steps are at the command line:

6. At the command line cd into the unzipped openbabel folder, for example: cd openbabel-3.1.1

7. Create a build directory: mkdir build

8. Change into the build directory: cd build

9. Using cmake, prepare the openbabel build files. This requires several specifications, the -DCMAKE_INSTALL_PREFIX specification should be the path to the site-packages folder of the virtual environment created above: cmake -DRUN_SWIG=ON -DPYTHON_BINDINGS=ON -DCMAKE_INSTALL_PREFIX=~/3env/lib/python3.6/site-packages ..

9a) If the above command causes a message at the command prompt that eigen cannot be found this can be fixed by stating its location, for example: cmake .. -DRUN_SWIG=ON -DPYTHON_BINDINGS=ON -DCMAKE_INSTALL_PREFIX=~/3env/lib/python3.6/site-packages -DEIGEN3_INCLUDE_DIR=/usr/local/Cellar/eigen/3.3.9/include/eigen3

10. Complete installation with: make install

11. Test that openbabel is functioning with: python

11a) Then inside the python interpreter use: import openbabel

11b) If this works fine (no error message) continue to step 12 If this returns: ModuleNotFoundError: No module named 'openbabel', then quit the python interpreter: quit()

11c) If error seen in step above, add the openbabel path to the python path, for example: export PYTHONPATH=~/3env/lib/python3.6/site-packages/lib/python3.6/site-packages/openbabel:$PYTHONPATH

12. Test that pybel is functioning with: python

12a) Then inside the python interpreter use: import pybel

12b) If no error message seen continue to next step. During testing this threw a relative import error which was corrected by changing the relevant line (given in the error message) in the pybel.py file (file location given in the error message) from "from . import openbabel as ob" to "import openbabel as ob"

13. Ensure pip and wheel up to date: pip install --upgrade pip wheel

14. Install PyCHAM and its dependencies in the virtual environment: python -m pip install --upgrade PyCHAM

Install is complete, to run PyCHAM please see Running.

Running

1. For model inputs, ensure you have: a .txt file chemical reaction scheme, a .xml file for converting the component names used in the chemical reaction scheme file to SMILE strings and a .txt file stating values of model variables (e.g. temperature) - see details about these three files below and note that example files are available in PyCHAM/input

2. Once Installation is complete and the appropriate environment has been activated (see Installation), use the command line to change into the top level directory PyCHAM (the directory above the PyCHAM main file).

3. There are two choices for starting up the programme. If you are new to PyCHAM, and/or have simulations that can be practically selected manually, then begin the programme from the command line to use PyCHAM via the graphical us