Getting started — PreciSo documentation

# Getting started

## Contents of this guide

In this page, you will learn more about :

- What PreciSo does, how it works ?

- How to use it without installing it on your computer (online user)

- How to use it in your projects (local user)

- How to modify or extend its capabilities (i.e. for developers)

## Overview

Preciso is a Python wrapper to the initial C++ project. It is designed to be lightweight and convenient, for both new and more experienced users.

Below is an example use case for PreciSo :

    import preciso
    import matplotlib.pyplot as plt

    # a configuration file specific to your material
    config_filename = "path/to/configuration_file.txt"

    # communication with PreciSo's C++ engine is transparent :
    results = preciso.runSimulation(config_filename)

    # results are available in the form of pandas DataFrames
    df = results.precipitation[0]

    plt.loglog(df["t[s]"],
               df["rmean_beta'[m]"],
               label="$R_{mean} (m)$")
    # *A beautiful figure appears*

With its concise high-level syntax, the Python wrapper allows to focus on physics (the parameters, the configuration file) instead of coding.

Note

PreciSo is available as a Python package. To use it, you will need Python 3, and a few other packages PreciSo is built on. If you have never heard of Python before, and don’t need to add new features PreciSo, the online version will be the best option.

Note

If you have any issue installing PreciSo, or if this documentation is somehow inaccurate, feel free to submit a ticket to the project’s Gitlab issue tracker.

## How to use PreciSo online (no installation)

To use PreciSo online, we recommended using Google Colab, Repl.it, CodeOcean, MyBinder, or any equivalent. Below is a step-by-step guide to using Google Colab.

Guide to use Colab

For other platforms, all you need is to find how to install custom python packages from the PyPi repo. From a Repl, it’s as simple as clicking the “Packages” button, typing “Preciso” and clicking “add”. The difference between Repl and Colab is that Repls are basically code snippets, whilst Colab is an interactive platform, and is much better at results visualization.

## Installation (local user)

Note

PreciSo supports Python 3 only. The current recommended version is 3.7.

In order to run PreciSo on your computer, you will need to :

- Get Python

- Install the PreciSo package.

For experienced users who have Python installed, installing PreciSo is as simple as `pip install preciso`. If you are not sure if you already have Python or how to install PreciSo, continue reading.

Warning

Installing Python the first time can be tedious, especially on Windows, and take a lot of disk space. If you only need very occasional use of PreciSo, you may want to use PreciSo online (see above).

The main barrier in installing Python is the possible existance of multiple instances of Python on your machine. If you already have one Python executable (possibly installed by another software) and install another one, it is likely that PreciSo will not be installed in the correct location, and it won’t work.

To avoid that, the recommended way is to use virtual environments. If you never used Python before, you can do it easily by installing Anaconda as described below.

Advanced users may prefer using miniconda (lightweight version of Anaconda), virtualenv or pipenv to create an environment in which they will install PreciSo and its dependencies. The step-by-step procedure is described in the Installing PreciSo for developers section below.

### Install with Anaconda (all OS)

1. Install a full Anaconda distribution, following the official documentation.

2. Open Anaconda, and launch Jupyter.

3. Go to the directory of your choice, and create a new Python3 notebook.

4. In the top cell, type `! pip install preciso`. Run the cell (Shift+Enter), and wait for the installation to finish.

5. In a new cell, type `import preciso`. This command should not fail.

6. Then, type `preciso.runSimulation(" ", debug=True)`. The output should report an error, and contain “Welcome to PreciSo v3.0”. This means the C++ engine of PreciSo was correctly started, and the installation was fully successful. If you don’t get this output, feel free to contact us for help.

## Installing PreciSo for developers

### On Linux/MacOS, using Miniconda

Miniconda is a distribution that includes `conda`, the package manager that will help you make a clean install of Python and PreciSo on any platform, with no root permissions. The famous Anaconda distribution is similar to Miniconda, but it includes a huge number of additional packages you don’t need for using PreciSo.

1. To get Python and Miniconda, follow the instructions from the official documentation of Miniconda and conda.

On MacOS and Linux, it should be :

    wget https://repo.anaconda.com/miniconda/Miniconda3-latest-MacOSX-x86_64.sh -O ~/miniconda.sh
    bash ~/miniconda.sh -b -p $HOME/miniconda

2. Once conda is installed, create an environment that lists all Preciso’s dependencies. For that, we’ll use a file to specify the packages we want to install, that contains :

    name: python-preciso
    channels:
      - anaconda
    dependencies:
      - python=3.7
      - numpy
      - pandas
      - matplotlib
      - scipy
      - jinja2
      - git
      - jupyter
      - seaborn

This file can be downloaded here.

3. Then, run one line at a time :

    # the first time you use conda

    # On macOS / Linux :
    $HOME/miniconda/bin/conda init

    # If conda is not found, you'll have to Google for a solution for your specific case/platform, or ask for help

    # create an environment from the file you downloaded
    conda env create -f environment.yml

    # activate the environment everytime you want to use it.
    # On Linux/MacOS can set an alias in your ~.bashrc or ~.bash_profile file for this one.
    conda activate python-preciso

    # Download the last version of Preciso
    git clone https://framagit.org/arnall/preciso.git

    # Install preciso in developer mode (-e)
    cd preciso
    pip install -e .

4. Check that the installation was successful. The following command should issue no error when ran in a new terminal.

    python3 -c 'import preciso; print("Preciso was successfully installed !")'

### Manual installation on Linux/Mac OS

If you already have a full Python installed and ready-to-go, and have git, you can follow these instructions.

Downlaod PreciSo package:

    git clone https://framagit.org/arnall/preciso.git preciso

Upgrade pip:

    python3 -m pip install --user --upgrade pip

In Jupyter, open a new terminal and enter the preciso folder:

    cd preciso

Install preciso package:

    pip install -e .

Check all requirements:

    pip install -r requirements.txt

### On Windows (using Anaconda)

To install Python requirements :

1. Install a full Anaconda distribution, following its official documentation.

Note

Alternatively, you can install miniconda by downloading the installer here. Then from a terminal, do :

    start /wait "" Miniconda3-latest-Windows-x86_64.exe /InstallationType=JustMe /RegisterPython=0 /S /D=%UserProfile%\miniconda

2. Download the environment file.

3. From Anaconda, import an environment and activate it.

For the installation of Preciso :

4. Open an Anaconda prompt, Jupyter terminal or jupyter notebook. Make sure you access your python-preciso environment by typing `conda env list`. It should display something like :

    # conda environments:
    #
    base                      /home/aallera/miniconda
    python-preciso         *  /home/aallera/miniconda/envs/python-preciso

Check the position of the `*` character, which means that `python-preciso` is the activated environment.

5. Create a folder and extract the archive found here (you’ll have to manually fetch new versions to get updates and bug fixes !)

or

5. Get preciso source code with

       git clone https://framagit.org/arnall/preciso.git

It will create a “preciso” folder in the current directory, that will contain the last version of the code. Updates can be done from this “preciso” directory with `git pull`.

6. Go to the folder that contains preciso’s `setup.py`:

       cd preciso

Then install preciso with pip (if error, try `pip3` instead):

    pip install -e .

If executed from a Jupyter notebook, do instead

    !pip install -e .

Relaunch Jupiter Notebook and check that preciso is importable from anywhere:

    import preciso; preciso.runSimulation("", temp=False)