Get started with biosnicar

Here you will find instructions for getting up and running with biosnicar, either via the web app or using the model code.

Web app

biosnicar is available as a web application. Simply direct your browser to

https://bit.ly/bio-snicar (opens in a new tab)

If you want to use biosnicar with a basic configuration, this is the simplest way. You can set your input configuration in the labelled fields on the left hand side of the screen and the plot in the centre of the screen will automatically update, providing the spectral albedo. You can also download the spectral albedo data as a csv file by clicking Download Data.

There are some restrictions on the parameter values and the set of available parameters in the web application. For example, the multilayer scheme is not available and only three different impurities are included. For complete control over the model configuration you can download and run the model yourself.

You can also run the app locally. Simply download the biosnicar repository, install using pip install -e . and then run ./start_app.py. The app will run at localhost:8501.

Python code

Installing Environment/Dependencies

If you want to run biosnicar in a local Python environment but you do not have Python installed, download Python >3.7. It is recommended to create a fresh environment using conda or venv specific to biosnicar. Once activated, install the project dependencies with:

pip install -r requirements.txt

The previous command may take an unreasonable amount of time to complete with anaconda. If that is the case, you can simply open the requirements.txt file and pip install each dependency in the fresh environment. Then, install biosnicar using:

pip install -e .

Finally, if you do not wish to install anything on your computer, but you use VSCode and Docker, then you can use the devcontainer config provided to run this code in a remote container. This requires the “remote containers” extension to be added to VSCode. Further instructions are available here: https://code.visualstudio.com/docs/remote/containers (opens in a new tab).

Running the model

The model driver (main.py) is in the root repository and all the core source code can be found in /biosnicar. From the top level directory (~/biosnicar_py`), run:

python main.py

This command will run the model with all the default settings from the config file inputs.yaml file. The user will see a list of output values printed to the console and a spectral albedo plot appear in a separate window. The code can also be run in an interactive session (Jupyter/iPython) in which case the relevant data and figure will appear in the interactive console, as well as in the command line outside of the top level directory, as long as the path to main.py is adjusted.

Most users will want to experiment with changing input parameters. This is achieved by adjusting the values in the config file inputs.yaml. The nature of each parameter is described in in-line annotations to guide the user, and detailed in the Inputs page. Invalid combinations of values will be rejected by our error-checking code. Most users should have no reason to modify any other file in this repository except for those in inputs.yaml.

More complex applications of the model code, for example model inversions, field/model comparisons etc are presented in the User guides menu.

We have also maintained a separate version of the biosnicar codebase that uses a “functional” progamming style rather than the object-oriented approach taken here. We refer to this as biosnicar Classic and it is available in the classic branch of this repository. It might be useful for people already familiar with FORTRAN or Matblab implementations from previous literature. The two branches are entirely equivalent in their simulations but very different in their programming style. The object oriented approach is preferred because it is more Pythonic, more flexible and easier to debug.

Choosing Inputs

It is straightforward to adjust the model configuration by updating the values in inputs.yaml. However there is a lot of nuance to setting up the model to provide realistic simulations, and the meaning of the various parameters is not always obvious. We will have a guide on this topic coming soon!

Please note that you can have multiple input files, even saved in an external directory with specific configurations and then loop through them in main.py. For example, you may wish to conduct an experiment with 10 different model configurations - in this case you could have ten inputsX.yaml files in an external directory. Then execute all the functions inside the default main.py in a simple for loop, assigning each file to input_files in turn. This is good for reproducibility as those config files can be archived.

Bio-optical model

The bio-optical model is generally run separately to the main model code because most users use the default optical properties provided in the downloaded repository. However, some users may wish to generate new files. To do this, simply call run_biooptical_model() in main.py after updating the biooptical section of inputs.yaml. We expect the bio-optical model to be used rarely.