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)¶
Install a full Anaconda distribution, following the official documentation.
Open Anaconda, and launch Jupyter.
Go to the directory of your choice, and create a new Python3 notebook.
In the top cell, type
! pip install preciso
. Run the cell (Shift+Enter), and wait for the installation to finish.In a new cell, type
import preciso
. This command should not fail.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.
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
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.
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 .
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 :
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
Download the environment file.
From Anaconda, import an environment and activate it.
For the installation of Preciso :
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.
Create a folder and extract the archive found here (you’ll have to manually fetch new versions to get updates and bug fixes !)
or
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
.
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)