tilupy 2.0.0__py3-none-any.whl

tilupy-2.0.0.dist-info/METADATA

@@ -0,0 +1,876 @@
+Metadata-Version: 2.4
+Name: tilupy
+Version: 2.0.0
+Summary: Thin-layer models unified processing tool
+Author-email: Marc Peruzzetto <m.peruzzetto@brgm.fr>
+License: CeCILL-C FREE SOFTWARE LICENSE AGREEMENT
+        
+        
+            Notice
+        
+        This Agreement is a Free Software license agreement that is the result
+        of discussions between its authors in order to ensure compliance with
+        the two main principles guiding its drafting:
+        
+            * firstly, compliance with the principles governing the distribution
+              of Free Software: access to source code, broad rights granted to
+              users,
+            * secondly, the election of a governing law, French law, with which
+              it is conformant, both as regards the law of torts and
+              intellectual property law, and the protection that it offers to
+              both authors and holders of the economic rights over software.
+        
+        The authors of the CeCILL-C (for Ce[a] C[nrs] I[nria] L[ogiciel] L[ibre])
+        license are:
+        
+        Commissariat à l'Energie Atomique - CEA, a public scientific, technical
+        and industrial research establishment, having its principal place of
+        business at 25 rue Leblanc, immeuble Le Ponant D, 75015 Paris, France.
+        
+        Centre National de la Recherche Scientifique - CNRS, a public scientific
+        and technological establishment, having its principal place of business
+        at 3 rue Michel-Ange, 75794 Paris cedex 16, France.
+        
+        Institut National de Recherche en Informatique et en Automatique -
+        INRIA, a public scientific and technological establishment, having its
+        principal place of business at Domaine de Voluceau, Rocquencourt, BP
+        105, 78153 Le Chesnay cedex, France.
+        
+        
+            Preamble
+        
+        The purpose of this Free Software license agreement is to grant users
+        the right to modify and re-use the software governed by this license.
+        
+        The exercising of this right is conditional upon the obligation to make
+        available to the community the modifications made to the source code of
+        the software so as to contribute to its evolution.
+        
+        In consideration of access to the source code and the rights to copy,
+        modify and redistribute granted by the license, users are provided only
+        with a limited warranty and the software's author, the holder of the
+        economic rights, and the successive licensors only have limited liability.
+        
+        In this respect, the risks associated with loading, using, modifying
+        and/or developing or reproducing the software by the user are brought to
+        the user's attention, given its Free Software status, which may make it
+        complicated to use, with the result that its use is reserved for
+        developers and experienced professionals having in-depth computer
+        knowledge. Users are therefore encouraged to load and test the
+        suitability of the software as regards their requirements in conditions
+        enabling the security of their systems and/or data to be ensured and,
+        more generally, to use and operate it in the same conditions of
+        security. This Agreement may be freely reproduced and published,
+        provided it is not altered, and that no provisions are either added or
+        removed herefrom.
+        
+        This Agreement may apply to any or all software for which the holder of
+        the economic rights decides to submit the use thereof to its provisions.
+        
+        
+            Article 1 - DEFINITIONS
+        
+        For the purpose of this Agreement, when the following expressions
+        commence with a capital letter, they shall have the following meaning:
+        
+        Agreement: means this license agreement, and its possible subsequent
+        versions and annexes.
+        
+        Software: means the software in its Object Code and/or Source Code form
+        and, where applicable, its documentation, "as is" when the Licensee
+        accepts the Agreement.
+        
+        Initial Software: means the Software in its Source Code and possibly its
+        Object Code form and, where applicable, its documentation, "as is" when
+        it is first distributed under the terms and conditions of the Agreement.
+        
+        Modified Software: means the Software modified by at least one
+        Integrated Contribution.
+        
+        Source Code: means all the Software's instructions and program lines to
+        which access is required so as to modify the Software.
+        
+        Object Code: means the binary files originating from the compilation of
+        the Source Code.
+        
+        Holder: means the holder(s) of the economic rights over the Initial
+        Software.
+        
+        Licensee: means the Software user(s) having accepted the Agreement.
+        
+        Contributor: means a Licensee having made at least one Integrated
+        Contribution.
+        
+        Licensor: means the Holder, or any other individual or legal entity, who
+        distributes the Software under the Agreement.
+        
+        Integrated Contribution: means any or all modifications, corrections,
+        translations, adaptations and/or new functions integrated into the
+        Source Code by any or all Contributors.
+        
+        Related Module: means a set of sources files including their
+        documentation that, without modification to the Source Code, enables
+        supplementary functions or services in addition to those offered by the
+        Software.
+        
+        Derivative Software: means any combination of the Software, modified or
+        not, and of a Related Module.
+        
+        Parties: mean both the Licensee and the Licensor.
+        
+        These expressions may be used both in singular and plural form.
+        
+        
+            Article 2 - PURPOSE
+        
+        The purpose of the Agreement is the grant by the Licensor to the
+        Licensee of a non-exclusive, transferable and worldwide license for the
+        Software as set forth in Article 5 hereinafter for the whole term of the
+        protection granted by the rights over said Software. 
+        
+        
+            Article 3 - ACCEPTANCE
+        
+        3.1 The Licensee shall be deemed as having accepted the terms and
+        conditions of this Agreement upon the occurrence of the first of the
+        following events:
+        
+            * (i) loading the Software by any or all means, notably, by
+              downloading from a remote server, or by loading from a physical
+              medium;
+            * (ii) the first time the Licensee exercises any of the rights
+              granted hereunder.
+        
+        3.2 One copy of the Agreement, containing a notice relating to the
+        characteristics of the Software, to the limited warranty, and to the
+        fact that its use is restricted to experienced users has been provided
+        to the Licensee prior to its acceptance as set forth in Article 3.1
+        hereinabove, and the Licensee hereby acknowledges that it has read and
+        understood it.
+        
+        
+            Article 4 - EFFECTIVE DATE AND TERM
+        
+        
+              4.1 EFFECTIVE DATE
+        
+        The Agreement shall become effective on the date when it is accepted by
+        the Licensee as set forth in Article 3.1.
+        
+        
+              4.2 TERM
+        
+        The Agreement shall remain in force for the entire legal term of
+        protection of the economic rights over the Software.
+        
+        
+            Article 5 - SCOPE OF RIGHTS GRANTED
+        
+        The Licensor hereby grants to the Licensee, who accepts, the following
+        rights over the Software for any or all use, and for the term of the
+        Agreement, on the basis of the terms and conditions set forth hereinafter.
+        
+        Besides, if the Licensor owns or comes to own one or more patents
+        protecting all or part of the functions of the Software or of its
+        components, the Licensor undertakes not to enforce the rights granted by
+        these patents against successive Licensees using, exploiting or
+        modifying the Software. If these patents are transferred, the Licensor
+        undertakes to have the transferees subscribe to the obligations set
+        forth in this paragraph.
+        
+        
+              5.1 RIGHT OF USE
+        
+        The Licensee is authorized to use the Software, without any limitation
+        as to its fields of application, with it being hereinafter specified
+        that this comprises:
+        
+           1. permanent or temporary reproduction of all or part of the Software
+              by any or all means and in any or all form.
+        
+           2. loading, displaying, running, or storing the Software on any or
+              all medium.
+        
+           3. entitlement to observe, study or test its operation so as to
+              determine the ideas and principles behind any or all constituent
+              elements of said Software. This shall apply when the Licensee
+              carries out any or all loading, displaying, running, transmission
+              or storage operation as regards the Software, that it is entitled
+              to carry out hereunder.
+        
+        
+              5.2 RIGHT OF MODIFICATION
+        
+        The right of modification includes the right to translate, adapt,
+        arrange, or make any or all modifications to the Software, and the right
+        to reproduce the resulting software. It includes, in particular, the
+        right to create a Derivative Software.
+        
+        The Licensee is authorized to make any or all modification to the
+        Software provided that it includes an explicit notice that it is the
+        author of said modification and indicates the date of the creation thereof.
+        
+        
+              5.3 RIGHT OF DISTRIBUTION
+        
+        In particular, the right of distribution includes the right to publish,
+        transmit and communicate the Software to the general public on any or
+        all medium, and by any or all means, and the right to market, either in
+        consideration of a fee, or free of charge, one or more copies of the
+        Software by any means.
+        
+        The Licensee is further authorized to distribute copies of the modified
+        or unmodified Software to third parties according to the terms and
+        conditions set forth hereinafter.
+        
+        
+                5.3.1 DISTRIBUTION OF SOFTWARE WITHOUT MODIFICATION
+        
+        The Licensee is authorized to distribute true copies of the Software in
+        Source Code or Object Code form, provided that said distribution
+        complies with all the provisions of the Agreement and is accompanied by:
+        
+           1. a copy of the Agreement,
+        
+           2. a notice relating to the limitation of both the Licensor's
+              warranty and liability as set forth in Articles 8 and 9,
+        
+        and that, in the event that only the Object Code of the Software is
+        redistributed, the Licensee allows effective access to the full Source
+        Code of the Software at a minimum during the entire period of its
+        distribution of the Software, it being understood that the additional
+        cost of acquiring the Source Code shall not exceed the cost of
+        transferring the data.
+        
+        
+                5.3.2 DISTRIBUTION OF MODIFIED SOFTWARE
+        
+        When the Licensee makes an Integrated Contribution to the Software, the
+        terms and conditions for the distribution of the resulting Modified
+        Software become subject to all the provisions of this Agreement.
+        
+        The Licensee is authorized to distribute the Modified Software, in
+        source code or object code form, provided that said distribution
+        complies with all the provisions of the Agreement and is accompanied by:
+        
+           1. a copy of the Agreement,
+        
+           2. a notice relating to the limitation of both the Licensor's
+              warranty and liability as set forth in Articles 8 and 9,
+        
+        and that, in the event that only the object code of the Modified
+        Software is redistributed, the Licensee allows effective access to the
+        full source code of the Modified Software at a minimum during the entire
+        period of its distribution of the Modified Software, it being understood
+        that the additional cost of acquiring the source code shall not exceed
+        the cost of transferring the data.
+        
+        
+                5.3.3 DISTRIBUTION OF DERIVATIVE SOFTWARE
+        
+        When the Licensee creates Derivative Software, this Derivative Software
+        may be distributed under a license agreement other than this Agreement,
+        subject to compliance with the requirement to include a notice
+        concerning the rights over the Software as defined in Article 6.4.
+        In the event the creation of the Derivative Software required modification 
+        of the Source Code, the Licensee undertakes that:
+        
+           1. the resulting Modified Software will be governed by this Agreement,
+           2. the Integrated Contributions in the resulting Modified Software
+              will be clearly identified and documented,
+           3. the Licensee will allow effective access to the source code of the
+              Modified Software, at a minimum during the entire period of
+              distribution of the Derivative Software, such that such
+              modifications may be carried over in a subsequent version of the
+              Software; it being understood that the additional cost of
+              purchasing the source code of the Modified Software shall not
+              exceed the cost of transferring the data.
+        
+        
+                5.3.4 COMPATIBILITY WITH THE CeCILL LICENSE
+        
+        When a Modified Software contains an Integrated Contribution subject to
+        the CeCILL license agreement, or when a Derivative Software contains a
+        Related Module subject to the CeCILL license agreement, the provisions
+        set forth in the third item of Article 6.4 are optional.
+        
+        
+            Article 6 - INTELLECTUAL PROPERTY
+        
+        
+              6.1 OVER THE INITIAL SOFTWARE
+        
+        The Holder owns the economic rights over the Initial Software. Any or
+        all use of the Initial Software is subject to compliance with the terms
+        and conditions under which the Holder has elected to distribute its work
+        and no one shall be entitled to modify the terms and conditions for the
+        distribution of said Initial Software.
+        
+        The Holder undertakes that the Initial Software will remain ruled at
+        least by this Agreement, for the duration set forth in Article 4.2.
+        
+        
+              6.2 OVER THE INTEGRATED CONTRIBUTIONS
+        
+        The Licensee who develops an Integrated Contribution is the owner of the
+        intellectual property rights over this Contribution as defined by
+        applicable law.
+        
+        
+              6.3 OVER THE RELATED MODULES
+        
+        The Licensee who develops a Related Module is the owner of the
+        intellectual property rights over this Related Module as defined by
+        applicable law and is free to choose the type of agreement that shall
+        govern its distribution under the conditions defined in Article 5.3.3.
+        
+        
+              6.4 NOTICE OF RIGHTS
+        
+        The Licensee expressly undertakes:
+        
+           1. not to remove, or modify, in any manner, the intellectual property
+              notices attached to the Software;
+        
+           2. to reproduce said notices, in an identical manner, in the copies
+              of the Software modified or not;
+        
+           3. to ensure that use of the Software, its intellectual property
+              notices and the fact that it is governed by the Agreement is
+              indicated in a text that is easily accessible, specifically from
+              the interface of any Derivative Software.
+        
+        The Licensee undertakes not to directly or indirectly infringe the
+        intellectual property rights of the Holder and/or Contributors on the
+        Software and to take, where applicable, vis-à-vis its staff, any and all
+        measures required to ensure respect of said intellectual property rights
+        of the Holder and/or Contributors.
+        
+        
+            Article 7 - RELATED SERVICES
+        
+        7.1 Under no circumstances shall the Agreement oblige the Licensor to
+        provide technical assistance or maintenance services for the Software.
+        
+        However, the Licensor is entitled to offer this type of services. The
+        terms and conditions of such technical assistance, and/or such
+        maintenance, shall be set forth in a separate instrument. Only the
+        Licensor offering said maintenance and/or technical assistance services
+        shall incur liability therefor.
+        
+        7.2 Similarly, any Licensor is entitled to offer to its licensees, under
+        its sole responsibility, a warranty, that shall only be binding upon
+        itself, for the redistribution of the Software and/or the Modified
+        Software, under terms and conditions that it is free to decide. Said
+        warranty, and the financial terms and conditions of its application,
+        shall be subject of a separate instrument executed between the Licensor
+        and the Licensee.
+        
+        
+            Article 8 - LIABILITY
+        
+        8.1 Subject to the provisions of Article 8.2, the Licensee shall be
+        entitled to claim compensation for any direct loss it may have suffered
+        from the Software as a result of a fault on the part of the relevant
+        Licensor, subject to providing evidence thereof.
+        
+        8.2 The Licensor's liability is limited to the commitments made under
+        this Agreement and shall not be incurred as a result of in particular:
+        (i) loss due the Licensee's total or partial failure to fulfill its
+        obligations, (ii) direct or consequential loss that is suffered by the
+        Licensee due to the use or performance of the Software, and (iii) more
+        generally, any consequential loss. In particular the Parties expressly
+        agree that any or all pecuniary or business loss (i.e. loss of data,
+        loss of profits, operating loss, loss of customers or orders,
+        opportunity cost, any disturbance to business activities) or any or all
+        legal proceedings instituted against the Licensee by a third party,
+        shall constitute consequential loss and shall not provide entitlement to
+        any or all compensation from the Licensor.
+        
+        
+            Article 9 - WARRANTY
+        
+        9.1 The Licensee acknowledges that the scientific and technical
+        state-of-the-art when the Software was distributed did not enable all
+        possible uses to be tested and verified, nor for the presence of
+        possible defects to be detected. In this respect, the Licensee's
+        attention has been drawn to the risks associated with loading, using,
+        modifying and/or developing and reproducing the Software which are
+        reserved for experienced users.
+        
+        The Licensee shall be responsible for verifying, by any or all means,
+        the suitability of the product for its requirements, its good working
+        order, and for ensuring that it shall not cause damage to either persons
+        or properties.
+        
+        9.2 The Licensor hereby represents, in good faith, that it is entitled
+        to grant all the rights over the Software (including in particular the
+        rights set forth in Article 5).
+        
+        9.3 The Licensee acknowledges that the Software is supplied "as is" by
+        the Licensor without any other express or tacit warranty, other than
+        that provided for in Article 9.2 and, in particular, without any warranty
+        as to its commercial value, its secured, safe, innovative or relevant
+        nature.
+        
+        Specifically, the Licensor does not warrant that the Software is free
+        from any error, that it will operate without interruption, that it will
+        be compatible with the Licensee's own equipment and software
+        configuration, nor that it will meet the Licensee's requirements.
+        
+        9.4 The Licensor does not either expressly or tacitly warrant that the
+        Software does not infringe any third party intellectual property right
+        relating to a patent, software or any other property right. Therefore,
+        the Licensor disclaims any and all liability towards the Licensee
+        arising out of any or all proceedings for infringement that may be
+        instituted in respect of the use, modification and redistribution of the
+        Software. Nevertheless, should such proceedings be instituted against
+        the Licensee, the Licensor shall provide it with technical and legal
+        assistance for its defense. Such technical and legal assistance shall be
+        decided on a case-by-case basis between the relevant Licensor and the
+        Licensee pursuant to a memorandum of understanding. The Licensor
+        disclaims any and all liability as regards the Licensee's use of the
+        name of the Software. No warranty is given as regards the existence of
+        prior rights over the name of the Software or as regards the existence
+        of a trademark.
+        
+        
+            Article 10 - TERMINATION
+        
+        10.1 In the event of a breach by the Licensee of its obligations
+        hereunder, the Licensor may automatically terminate this Agreement
+        thirty (30) days after notice has been sent to the Licensee and has
+        remained ineffective.
+        
+        10.2 A Licensee whose Agreement is terminated shall no longer be
+        authorized to use, modify or distribute the Software. However, any
+        licenses that it may have granted prior to termination of the Agreement
+        shall remain valid subject to their having been granted in compliance
+        with the terms and conditions hereof.
+        
+        
+            Article 11 - MISCELLANEOUS
+        
+        
+              11.1 EXCUSABLE EVENTS
+        
+        Neither Party shall be liable for any or all delay, or failure to
+        perform the Agreement, that may be attributable to an event of force
+        majeure, an act of God or an outside cause, such as defective
+        functioning or interruptions of the electricity or telecommunications
+        networks, network paralysis following a virus attack, intervention by
+        government authorities, natural disasters, water damage, earthquakes,
+        fire, explosions, strikes and labor unrest, war, etc.
+        
+        11.2 Any failure by either Party, on one or more occasions, to invoke
+        one or more of the provisions hereof, shall under no circumstances be
+        interpreted as being a waiver by the interested Party of its right to
+        invoke said provision(s) subsequently.
+        
+        11.3 The Agreement cancels and replaces any or all previous agreements,
+        whether written or oral, between the Parties and having the same
+        purpose, and constitutes the entirety of the agreement between said
+        Parties concerning said purpose. No supplement or modification to the
+        terms and conditions hereof shall be effective as between the Parties
+        unless it is made in writing and signed by their duly authorized
+        representatives.
+        
+        11.4 In the event that one or more of the provisions hereof were to
+        conflict with a current or future applicable act or legislative text,
+        said act or legislative text shall prevail, and the Parties shall make
+        the necessary amendments so as to comply with said act or legislative
+        text. All other provisions shall remain effective. Similarly, invalidity
+        of a provision of the Agreement, for any reason whatsoever, shall not
+        cause the Agreement as a whole to be invalid.
+        
+        
+              11.5 LANGUAGE
+        
+        The Agreement is drafted in both French and English and both versions
+        are deemed authentic.
+        
+        
+            Article 12 - NEW VERSIONS OF THE AGREEMENT
+        
+        12.1 Any person is authorized to duplicate and distribute copies of this
+        Agreement.
+        
+        12.2 So as to ensure coherence, the wording of this Agreement is
+        protected and may only be modified by the authors of the License, who
+        reserve the right to periodically publish updates or new versions of the
+        Agreement, each with a separate number. These subsequent versions may
+        address new issues encountered by Free Software.
+        
+        12.3 Any Software distributed under a given version of the Agreement may
+        only be subsequently distributed under the same version of the Agreement
+        or a subsequent version.
+        
+        
+            Article 13 - GOVERNING LAW AND JURISDICTION
+        
+        13.1 The Agreement is governed by French law. The Parties agree to
+        endeavor to seek an amicable solution to any disagreements or disputes
+        that may arise during the performance of the Agreement.
+        
+        13.2 Failing an amicable solution within two (2) months as from their
+        occurrence, and unless emergency proceedings are necessary, the
+        disagreements or disputes shall be referred to the Paris Courts having
+        jurisdiction, by the more diligent Party.
+        
+        
+        Version 1.0 dated 2006-09-05.
+Project-URL: Homepage, https://github.com/marcperuz/tilupy
+Keywords: thin-layer,shallow-water,display,simulation,model,processing,benchmark
+Classifier: License :: CeCILL-C Free Software License Agreement (CECILL-C)
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: seaborn
+Requires-Dist: requests
+Requires-Dist: scipy
+Requires-Dist: pytopomap
+Provides-Extra: test
+Requires-Dist: pytest; extra == "test"
+Provides-Extra: dev
+Requires-Dist: pipreqs; extra == "dev"
+Provides-Extra: gis
+Requires-Dist: rasterio; extra == "gis"
+Requires-Dist: shapely; extra == "gis"
+Dynamic: license-file
+
+# tilupy
+
+[![Anaconda-Server Badge](https://anaconda.org/conda-forge/tilupy/badges/version.svg)](https://anaconda.org/conda-forge/tilupy) [![Anaconda-Server Badge](https://anaconda.org/conda-forge/tilupy/badges/downloads.svg)](https://anaconda.org/conda-forge/tilupy)
+
+- [Description](#description)
+- [Installation with pip](#installation-pip)
+- [Installation with anaconda](#installation-conda)
+- [Quick start](#quick-start)
+  - [Prepare simulations](#prepare-simus)
+  - [Get simulation results](#simu-results)
+  - [Process simulation results in python script](#process-simus-python)
+  - [Process simulation results in command line](#process-simus-cmd)
+- [Models references](#models-refs)
+  - [Shaltop](#ref-shaltop)
+  - [r.avaflow](#ref-ravaflow) 
+ 
+
+## Description <a name="description"></a>
+
+`tilupy` (ThIn-Layer Unified Processing in pYthon) package is meant as a top-level tool for processing inputs and outputs of thin-layer geophysical
+flow simulations on general topographies.
+It contains one submodule per thin-layer model for writing and reading raw inputs and outputs of the model. 
+Outputs are then easily compared between different simulations / models. The models themselves are not part of this package and must
+be installed separately.
+
+Note that `tilupy` is still under development, thus only minimal documentation is available at the moment, and testing is underway.
+Contributions are feedback are most welcome. Reading and writing is available for the `SHALTOP` model (most commonly used by the author) and `r.avaflow`
+(only partly maintained).
+
+## Installation with pip <a name="installation-pip"></a>
+
+To install `tilupy` from GitHub or PyPi, you'll need to have `pip` installed on your computer. 
+
+It is strongly recommended to install `tilupy` in a virtual environnement dedicated to this package. This can be done with `virtualenv`
+(see the documentation e.g. [here](https://packaging.python.org/en/latest/guides/installing-using-pip-and-virtual-environments/)).
+Create the environnement with :
+
+```bash
+python -m venv /path/to/myenv
+```
+
+and activate it, on Linux:
+
+```bash
+source /path/to/myenv/bin/activate
+```
+
+and on Windows:
+
+```cmd.exe
+\path\to\myenv\Scripts\activate
+```
+
+Alternatively, if you are more used to Anaconda :
+
+```bash
+conda create -n tilupy pip
+conda activate tilupy
+```
+
+or equivalently with Mamba :
+
+```bash
+mamba create -n tilupy pip
+mamba activate tilupy
+```
+
+Before installing with `pip`, make sure `pip`, `steuptools` and `wheel` are up to date
+
+```
+python -m pip install --upgrade pip setuptools wheel
+```
+
+### Latest stable realease from PyPi <a name="pypi-install"></a>
+
+```
+python -m pip install tilupy
+```
+
+### Development version on from GitHub <a name="source-install"></a>
+
+Download the GithHub repository [here](https://github.com/marcperuz/tilupy), or clone it with
+
+```
+git clone https://github.com/marcperuz/tilupy.git
+```
+
+Open a terminal in the created folder and type:
+
+```
+python -m pip install .
+```
+
+## Installation with from conda-forge <a name="installation-conda"></a>
+
+The latest stable version of `tilupy` on PyPi is also (supposedly) distributed on `conda-forge`. It can be intalled with Anaconda (or any equivalent) with
+
+```
+conda install conda-forge::tilupy
+```
+
+## Quick start <a name="quick-start"></a>
+
+We give here a simple example to prepare simulations for SHALTOP, and process the results. The corresponding scripts can be found in `examples/frankslide`
+
+### Prepare simulations <a name="prepare-simus"></a>
+
+Import the different required modules :
+
+```python
+import os
+
+# Read an write rasters
+import tilupy.raster
+# Functions to download examples of elevation and initial mass rasters
+import tilupy.download_data
+#Submodule used to prepare Shaltop simulations
+import tilupy.models.shaltop.initsimus as shinit
+```
+
+Define the folder where input data will be downloaded and simulations carried out :
+
+```python
+FOLDER_BASE = '/path/to/myfolder'
+```
+
+Import data from GitHub, and create subfolder for simulation results
+
+```python
+folder_data = os.path.join(FOLDER_BASE, 'rasters')
+os.makedirs(folder_data, exist_ok=True)
+#raster_topo and raster_mass are the paths to the topography and initial mass rasters
+raster_topo = tilupy.download_data.import_frankslide_dem(folder_out=folder_data)
+raster_mass = tilupy.download_data.import_frankslide_pile(folder_out=folder_data)
+# Create folder for shaltop simulations
+folder_simus = os.path.join(FOLDER_BASE, 'shaltop')
+os.makedirs(folder_simus, exist_ok=True)
+```
+
+Convert downloaded rasters to Shaltop input file type, and store the properties of the resulting grid
+
+```python
+shinit.raster_to_shaltop_txtfile(raster_topo,
+                                 os.path.join(folder_simus, 'topography.d'))
+axes_props = shinit.raster_to_shaltop_txtfile(raster_mass,
+                                              os.path.join(folder_simus, 'init_mass.d'))
+```
+
+Initiate simulations parameters. See the SHALTOP documentation for details.
+
+```python
+params = dict(nx=axes_props['nx'], ny=axes_props['ny'],
+              per=axes_props['nx']*axes_props['dx'],
+              pery=axes_props['ny']*axes_props['dy'],
+              tmax=100, # Simulation maximum time in seconds (not comutation time)
+              dt_im=10, # Time interval (s) between snapshots recordings
+              file_z_init = 'topography.d', # Name of topography input file
+              file_m_init = 'init_mass.d',# name of init mass input file
+              initz=0, # Topography is read from file
+              ipr=0, # Initial mass is read from file
+              hinit_vert=1, # Initial is given as vertical thicknesses and 
+              # must be converted to thicknesses normal to topography
+              eps0=1e-13, #Minimum value for thicknesses and velocities
+              icomp=1, # choice of rheology (Coulomb with constant basal friction)
+              x0=1000, # Min x value (used for plots after simulation is over)
+              y0=2000) # Min y value (used for plots after simulation is over)
+```
+
+Finally, prepare simulations for a set of given rheological parameters (here, three basal friction coefficients)
+
+```python
+deltas = [15, 20, 25]
+for delta in deltas:
+    params_txt = 'delta_{:05.2f}'.format(delta).replace('.', 'p')
+    params['folder_output'] = params_txt # Specify folder where outputs are stored
+    params['delta1'] = delta # Specify the friction coefficient
+    #Write parameter file
+    shinit.write_params_file(params, directory=folder_simus,
+                             file_name=params_txt + '.txt')
+    #Create folder for results (not done by shlatop!)
+    os.makedirs(os.path.join(folder_simus, params_txt), exist_ok=True)
+```
+
+You must then run the simulations (see Shaltop documentation)
+
+### Get simulation results <a name="simu-results"></a>
+
+Simulation results are read from a `Results` class. Main functions are defined in the parent class `tilupy.read.Results`, and each model has its own inheretied class `tilupy.models.[model_name].read.Results`. A class instance for a given model can be initiated with
+
+```python
+res = tilupy.read.get_results([model_name], **kwargs)
+```
+
+where `kwargs must be adapted to the considered model. For instance with Shaltop and the example above, the results of the simulation with a friction angle of 25 must be initiated as :
+
+```python
+res = tilupy.read.get_results('shaltop', folder=folder_simus, file_params='delta_25p00.txt)
+```
+
+The topography and axes can then directly be read from `res` :
+
+```python
+x, y, z = res.x, res.y, res.z
+import matplotlib.pyplot as plt
+plt.imshow(z)
+```
+
+`z[i, j]` is the altitude at `flip(y[i])` and `x[j]`. Thus `z[0, 0]` corresponds to the North-West corner of the topography. 
+
+Specific simulation outputs can be extracted with 
+
+```python
+h_res = res.get_output(res_name)
+```
+
+where `res_name` must chosen among
+
+- `h` : Flow thickness in the direction perpendicular to the topography
+- `hvert` : Flow thickness in the vertical direction
+- `ux` and `uy` : Flow velocity in the X and Y direction (check whether it is in the cartesian reference frame or not)
+- `u` : Norm of the flow velocity
+- `hu` : Momentum (thickness * flow velocity)
+- `hu2` : Kinetic energy (thickness * square flow velocity)
+
+It is also possible to extract 2D spatial static characteritics of the flow by using any of the previous states with `_[operation]`, where
+`[operation]` is chosen among, `max`, `mean`, `std`, `sum`, `min`, `final`, `initial`. For instance `h_max` is a 2D array with the
+maximum simulated thickness at each point of the grid. `h_final` is the simulated thickness at the end of the simulation.
+`tilupy` will load these characteristics directly from the simulation output when possible (e.g. Shaltop records a maximum thickness array),
+or compute then from the available data. For instance, if the simulation results contains a file whith the maximum thickness, `h_max` will be
+read from this file. Otherwise, `h_max` is computed from the simulation recorded temporal snapshots (which is supposedly less precise).
+
+For instance, to load the recorded thicknesses in the current example :
+
+```python
+res_name = 'h' 
+h_res = res.get_output(res_name) # Thicknesses recorded at different times
+# h_res.d is a 3D numpy array of dimension (len(x) x len(y) x len(h_res.t))
+plt.imshow(h_res.d[:, :, -1]) # Plot final thickness.
+t = h_res.t # Get times of simulation outputs.
+```
+
+And to load the maximum thickness array :
+
+```python
+res_name = 'h_max'
+h_max_res = res.get_output(res_name) #h_max_res is read directly from simulation
+# results when possible, and is deduced from res.get_output('h') otherwise
+# h_max_res.d is a 2D numpy array of dimension (len(x) x len(y))
+plt.imshow(h_max_res.d)
+```
+
+### Process simulation results in python script <a name="process-simus-python"></a>
+
+`tilupy`can be used to plot the results as images, where the flow state (thickness, velocity, ...)
+is shown with a colorscale on the underlying topography. Plots can be thouroughly customized (documentation not available yet).
+
+For instance, the following code plots the flow thickness at each recorded time step, with a constant colorscale vraying from 0.1 to
+100 m. The topography is represented as a shaded relief with thin contour lines every 10 m, and bold contour_lines every 100 m. Plots are saved
+in a folder created in `folder_out`, but not displayed in the terminal (if you work in a developping environnement such as `spyder`).
+
+```python
+topo_kwargs = dict(contour_step=10, step_contour_bold=100) # give interval between thin and bold contour lines
+params_files = 'delta_*.txt'
+tilupy.cmd.plot_results('shaltop', 'h', params_files, folder_simus,
+                        save=True, display_plot=False, figsize=(15/2.54, 15/2.54),
+                        vmin=0.1, vmax=100, fmt='png',
+                        topo_kwargs=topo_kwargs)
+```
+
+The following code acts similarly, but plots the maximum thickness instead, and used a segmented colormap given by `cmap_intervals`.
+
+```python
+tilupy.cmd.plot_results('shaltop', 'h_max', params_files, folder_simus,
+                        save=True, display_plot=False, figsize=(15/2.54, 15/2.54),
+                        cmap_intervals=[0.1, 5, 10, 25, 50, 100],
+                        topo_kwargs=topo_kwargs)
+```
+
+It is also possible to save outputs back to rasters. The following code save all recorded thicknesses snapshots as tif files in a new folder
+created in `folder_out`.
+
+```python
+tilupy.cmd.to_raster('shaltop', 'h_max', params_files,
+                     folder_simus, fmt='tif')
+```
+
+### Process simulation results in command line <a name="process-simus-cmd"></a>
+
+`tilupy` comes with command line scripts to allow for quick processing of results. They work similarly as the functions `tilupy.cmd.plot_results` and `tilupy.cmd.to_raster`, 
+although there are less options. 
+
+`tilupy_plot` will automatically plot and save results in a new folder `plot` located in the simulation output folder specified in the parameter file :
+
+```
+tilupy_plot [-h] [-n RES_NAME] [-p PARAM_FILES] [-f FOLDER] [--fmt FMT] [--vmin VMIN] [--vmax VMAX]
+                   [--minval_abs MINVAL_ABS]
+                   [model]
+```
+
+`RES_NAME` can be any of the strings listed in the previous section. For instance, to plot all thicknesses snaphsots from shaltop simulations in the current folder, type `tilupy_plot shaltop -n h`. If parameters files are located in `another/folder`, type, `tilupy shaltop -n h -f another/folder`. Similarly, to save  thicknesses snapshots as ascii rasters, use `tilupy_to_raster shaltop -n h --fmt asc`.
+
+```
+tilupy_to_raster [-h] [-n RES_NAME] [-p PARAM_FILES] [-f FOLDER] [--fmt {tif,tiff,txt,asc,ascii}] model
+```
+
+With both commands you can use the `-h` option do print help.
+
+## Models references <a name="models-refs"></a>
+
+We provide here a basic descriptions of models compatible with `tilupy`. The list of references is not exhaustive. 
+
+### Shaltop <a name="ref-shaltop"></a>
+
+`shaltop` models gravitational flow models over general topographies with small slope variation (small curvature) and friction. The equations are expressed in a horizontal/vertical reference frame and the shallow approximation is imposed in the direction normal to the slope. `shaltop` is not yet freely available. If you are interested, contact [m.peruzzetto@brgm.fr](mailto:m.peruzzetto@brgm.fr) or [mangeney@ipgp.fr](mailto:mangeney@ipgp.fr). 
+
+- Bouchut, F., Mangeney-Castelnau, A., Perthame, B., Vilotte, J.-P., 2003. A new model of Saint Venant and Savage–Hutter type for gravity driven shallow water flows. Comptes Rendus Mathématique 336, 531–536. [https://doi.org/10.1016/S1631-073X(03)00117-1](https://doi.org/10.1016/S1631-073X(03)00117-1)
+- Bouchut, F., Westdickenberg, M., 2004. Gravity driven shallow water models for arbitrary topography. Communications in Mathematical Sciences 2, 359–389. [https://doi.org/10.4310/CMS.2004.v2.n3.a2](https://doi.org/10.4310/CMS.2004.v2.n3.a2)
+- Mangeney-Castelnau, A., Bouchut, F., Vilotte, J.P., Lajeunesse, E., Aubertin, A., Pirulli, M., 2005. On the use of Saint Venant equations to simulate the spreading of a granular mass: numerical simulation of granular spreading. Journal of Geophysical Research: Solid Earth 110, B09103. [https://doi.org/10.1029/2004JB003161](https://doi.org/10.1029/2004JB003161)
+- Mangeney, A., Bouchut, F., Thomas, N., Vilotte, J.P., Bristeau, M.O., 2007. Numerical modeling of self-channeling granular flows and of their levee-channel deposits. Journal of Geophysical Research 112, F02017. [https://doi.org/10.1029/2006JF000469](https://doi.org/10.1029/2006JF000469)
+
+
+### r.avaflow <a name="ref-ravaflow"></a>
+
+`r.avaflow` is a GIS-supported open source software tool for the simulation of complex, cascading mass flows over arbitrary topography. It can be downloaded, along with the associated documentation, on the officiel [website](https://www.landslidemodels.org/r.avaflow/). Note that the integration of `r.avaflow` in `tilupy` is partial and potentially not adapted to new releases of `r.avaflow`. 
+
+- Mergili, M., Fischer, J.-T., Krenn, J., Pudasaini, S.P., 2017. r.avaflow v1, an advanced open source computational framework for the propagation and interaction of two-phase mass flows. Geoscientific Model Development Discussions 10, 553–569. [https://doi.org/10.5194/gmd-10-553-2017](https://doi.org/10.5194/gmd-10-553-2017)
+- Pudasaini, S.P., Mergili, M., 2019. A Multi-Phase Mass Flow Model. Journal of Geophysical Research: Earth Surface 124, 2920–2942. [https://doi.org/10.1029/2019JF005204](https://doi.org/10.1029/2019JF005204)
+
+### Lave2D <a name="ref-Lave2D"></a>
+
+`Lave2D` is a software developped by the INRAE for the modeling of debris flows with the Herschel-Bulkley rheology.
+
+- Laigle, D., Hector, A.-F., Hübl, J., Rickenmann, D., 2006. Confrontation de la simulation numérique de l’étalement de laves torrentielles boueuses à des observations d’événements réels. La Houille Blanche 92, 105–112. https://doi.org/10.1051/lhb:2006108
+- Rickenmann, D., Laigle, D., McArdell, B.W., Hübl, J., 2006. Comparison of 2D debris-flow simulation models with field events. Computational Geosciences 10, 241–264. https://doi.org/10.1007/s10596-005-9021-3