If you used git during installation, you can easily get updates by entering

git pull

in a git bash or in a Terminal in your proffastpylot folder. This command will download all available updates. If you downloaded PROFFASTpylot as zip file, you need to redo all steps of this installation script. 

Installation - Content 

1. Prerequisites

2. Download the PROFFASTpylot repository

3. Get PROFFAST and copy it to proffastpylot

4. Create a virtual environment in python

5. Install PROFFASTpylot

6. Resulting folder structure

7. Test the installation by running an example dataset

8. Getting Updates 

1. Prerequisites

For using PROFFASTpylot you need Python 3.7 or newer. The PROFFAST and PROFFASTpylot can be used in Windows and Linux environments. A step-by-step installation instruction for both environments is given in the following. We did not test the software for Mac environments. 

2. Download the PROFFASTpylot repository

Clone the PROFFASTpylot repository using git 

We recommend downloading the files using git (https://www.git-scm.com). 
It will make future updates easier. 

git clone https://github.com/coccon/proffastpylot.git

A folder proffastpylot containing all program files will be created. 

Alternatively: Download the PROFFASTpylot repository as a zip file

If you don't want to use git, you can instead download and unpack the zip file https://github.com/coccon/proffastpylot/archive/refs/heads/main.zip

Extracting it will create the folder proffastpylot. 

3. Get PROFFAST and copy it to the proffastpylot folder 

Download PROFFAST

Download PROFFAST Version 2.4 from the KIT website:
https://www.coccon.kit.edu/69.php

Compile PROFFAST (only Linux) 

For Windows users, the executables are already provided, on Linux systems you need to create them from source.

If not present on your system, first install the gfortan compiler.

Secondly, run the installation script for compilation from the prf folder.

cd prf/
bash install_proffast_linux.sh 

Copy the prf directory

Copy the prf folder that was extracted from the zip file into proffastpylot.

4. Create a virtual environment in python 

We recommend using a virtual environment (venv) to avoid conflicts between any other packages or Python modules.

1. (Only first time) Navigate to the proffastpylot folder using a terminal.

2. (Only first time) Enter python -m venv .venv.
   This command will create a folder named .venv, which contains the virtual environment

3. Activate the virtual environment every time you run PROFFASTpylot with

   • Windows PowerShell: .\.venv\Scripts\Activate.ps1

   • Windows Commandline: .\.venv\Scripts\activate

   • Linux: source .venv/bin/activate

4. To deactivate the virtual environment you can run deactivate

Note that all packages to be installed with pip install . will only affect the virtual environment and not the local Python installation.
In case of a problem, take a look at the Troubleshooting article of the PROFFASTpylot documentation on GitHub.

You need to activate the virtual environment before each run of PROFFASTpylot by executing the command in step 3, the other steps need to be executed only the first time.

5. Install the PROFFASTpylot repository

Activate the virtual environment (see above).

Navigate to proffastpylot and enter

pip install --editable .

6. Resulting folder structure

If you follow exactly the installation guide your folder structure should look like the following:

proffastpylot
├── .venv
│   ├── ...
├── docs
│   ├── ...
├── example
│   ├── input_sodankyla_example.yml
│   ├── log_type_pressure.yml
│   └── run.py
├── prf
│   ├── docs
│   ├── inp_fast
│   ├── inp_fwd
│   ├── preprocess
│   ├── source
│   ├── out_fast
│   └── wrk_fast
├── prfpylot
│   ├── ...
└── setup.py 

7. Test the installation by running an example dataset

To test the installation, we provide example raw data and a reference result file to compare the file to. The example can be executed by navigating to the example folder and executing the `run_*.py` scripts (please ensure that your virtual environment is activated). When first running the program, it will ask you to download the example file data to your local computer.

After the run is complete, please compare your results to the data given in example\Reference_Output_Example_Sodankyla.csv. The deviations should be less than 0.1 ppm for XCO2, 0.1 ppb for XCH4 and 0.1 ppb for XCO. 

8. Getting Updates

If you used git during installation, you can easily get updates by entering

git pull

in a git bash or in a Terminal in your proffastpylot folder. This command will download all available updates. If you downloaded PROFFASTpylot as zip file, you need to redo all steps of this installation script.

Usage - Content 

1. General use

   • Input file creation

   • Starting the run

2. Special case: Process spectra directly

3. Folder Structure 
    

1. General use

Ready-to-use Example
You can follow the usage of PROFFASTpylot with the help of an example from Sodankylä which is provided in examples/run_sodankyla_retrieval.py. The example input data (i.e., the example interferogram, map, and pressure files) as well as proffast will be downloaded automatically when running any of the example scripts for the first time. On Linux, Proffast will be compiled automatically; on other operating systems, you will have to follow the proffast installation instructions. 

Executing PROFFAST with the PROFFASTpylot takes two steps

1. Create an input file with the required information

2. Execute PROFFASTpylot via a Python script

Both steps will be explained in more detail, in the following. 

Input file creation

The input file (stored in the YAML format) contains all the key information required by PROFFASTpylot and PROFFAST, e.g., the location of the input and output files, or meta-data about the data to be processed. An example with explanations (example_sodankyla_input.yml) is provided. It contains all options that are required to process the example data set. Adjust this file to your requirements. 

Starting the processing 

For starting the processing, you need to create an instance of the Pylot class with an input file. 

from prfpylot.pylot import Pylot

if __name__ == "__main__":
    input_file = "config/input_sodankyla_example.yml"
    MyPylot = Pylot(input_file=input_file)

Note that the if __name__ == "__main__" statement needs to be placed before initializing Pylot to prevent problems with the multiprocessing on Windows. 

Afterwards all steps of PROFFAST can be executed automatically one after the other: 

MyPylot.run(n_processes)

Alternatively, you can run all steps of PROFFAST individually with the following commands: 

n_processes = 2
try:
    MyPylot.run_preprocess(n_processes)
    MyPylot.run_pcxs(n_processes)
    MyPylot.run_inv(n_processes)
    MyPylot.combine_results()
finally:
    MyPylot.clean_files()

You can execute run.py to test this with the example data provided. 

Alternative way of starting the processing

In the case above, we loaded a YAML file to get the input parameters. However, when processing larger datasets or embedding PROFFASTpylot into an larger environment, it can be helpful to pass the input parameters directly as a dictionary instead of a file. In this case the initialization would look like: 

from prfpylot.pylot import Pylot

input_dict = {
    "instrument_number": "SN039",
    "site_name": "Sodankyla",
    "site_abbrev": "so",
    # ... and all other needed parameters
}

if __name__ == "__main__":
    MyPylot = Pylot(input_file=input_dict)

2. Special case: Process spectra directly 

If the spectra are already available, set the option start_with_spectra to True in the input file. The path to the spectra is given to PROFFASTpylot via the analysis_path entry. Note, that the folder analysis_path must have the following substructure: analysis/SiteName_InstrumentNumber/YYMMDD. Afterwards, Pylot.run() will not execute preprocess. 

3. Folder structure 

The results results will be created automatically. Please see the Folder structure article at GitHub about how the results are organized.