search

kellykochanski / rescal-snow

A model of dunes and snow-waves
GNU General Public License v3.0
12 stars 5 forks source link

readme

Rescal-snow

A model of dunes and snow waves

status

  1. Motivation
  2. Getting started
    1. Prerequisites
    2. Dependencies
    3. Download
    4. Installation
  3. Features
    1. Example 1: a snow cone
    2. Example 2: sintering snow
    3. Example 3: dune growth by snowfall
    4. Example 4: parameter space exploration
  4. References and further reading
  5. Community guidelines
    1. Citation
    2. Support
    3. Contributing
  6. Contributors
  7. License

1. Motivation

When wind blows over snow, it self-organizes. This forms surface features, such as ripples and dunes, that alter the reflectivity and thermal conductivity of the snow.

Studying these features in the field is cold and challenging (we've tried), so we created rescal-snow to enable snow scientists to study snow features in controlled numerical experiments. We hope that this model will be useful to researchers in snow science, geomorphology, and polar climate.

Rescal-snow is able to simulate:

Rescal-snow is also designed for robust, reproducible science, and contains tools for high-performance computing, data management, and data analysis, including:

2. Getting started

2.1 Prerequisites

We assume you have reasonable familiarity with bash and terminal commands. If you have never used bash, we recommend you stop and work through a short tutorial. (Our favorite is 'The Unix Shell' from Software Carpentry.) If you modify rescal-snow, you will need to modify and compile C code. We have also included some setup and analysis tools (used in Example 5) written in Python.

2.2 Dependencies

On a Debian-based/Ubuntu Linux machine, the dependencies can be acquired using: 

sudo apt install gcc cmake make libpng-dev zlib1g-dev python3 python3-numpy python3-pandas python3-scipy

On most machines, the Python packages can also be acquired using:

pip3 install numpy pandas scipy

2.3 Download

Download rescal-snow by cloning this repository with git:

git clone https://github.com/kellykochanski/rescal-snow.git
cd rescal-snow

You may also download the repository manually from Github.

2.4 Installation

In a terminal, navigate into the main rescal-snow directory (shown above). Run:

mkdir build
cd build
cmake -Wno-dev -DCMAKE_BUILD_TYPE=Release .. #Debug can be used instead of Release
make -j 4                                    #Adjust to the number of cores you have for a speedy build

3. Features

The examples below are fully described in the tutorial: docs/rescal-snow-tutorial.md. The docs folder also contains descriptions of additional configuration and analysis options; check these if you're looking for functionality not found in the tutorial.

3.1 Sand and snow dunes

The default configuration for Rescal-snow simulates snow (or sand) dune formation. This simulates processes including air flow; grain entrainment, saltation, suspension and deposition; and granular avalanches.

In these conditions, a pile of sand/snow (left) evolves into a dart-shaped barchan dune (middle), then dwindles as grains blow away without being resupplied (right).

Initial condition, t = 0t0 t = 30t0 t = 90t0

Each of the three images above shows a shaded top-down view of a dune (top left), cross-sections through the dune, along the dashed lines (middle left, top right), and a cross-section showing the pressure intensity in the fluid (bottom left).

3.2 Sintering snow

Snow cohesion increases over time: this is called sintering. Rescal-snow is able to simulate the transition of loose (beige) grains into sintered (light purple) grains within waves and dunes.

3.3 Dune growth by snowfall

Rescal-snow simulates snow by adding loose grains to the top of the simulation. The gif at the top of this page shows a height-map of a field of dunes and waves growing during snowfall.

3.4 Parallel instances and parameter space exploration

We believe that building robust, trustworthy models is much simpler when it's easy to make many model runs.

Rescal-snow contains a series of tools for running many simulation instances in parallel, and managing the associated flows of input and output data.

The following phase diagram shows images produced by ten parallel runs simulating different rates of snowfall (lambda_I) and wind speed (Tau_min).

snowfall-wind phase diagram

4. References and further reading

The docs folder contains additional information on performance and parallelization issues, model inputs and configuration, model calibration and validation, and development history

For more background on snow dunes, sintering, and self-organization, see:

For more information about the backend function of the cellular automaton and lattice gas model, see:

5. Community guidelines

We encourage you to interact with the project through Github (see below). This will allow easy integration of your changes and prevent rescal-snow from fragmenting excessively. We use this git workflow, with the expectation that new changes will be tested on the examples in the README, docs, or tutorials. If you're not familiar with git, see the software carpentry git tutorial.

5.1 Citation

Do you want to incentivize developers to build and maintain the software you need? Cite us!

This software inherits many features from the Real-Space Cellular Automaton Laboratory, ReSCAL. Credit them by citing:

5.2 Support

If you have challenges or questions, look at the material under 'further information' or reach out to us.

Issues should be reported using Github's issue tracking function on this repository, here.

Issues which cannot be handled via Github can be addressed to

Kelly Kochanski
kelly.kochanski@gmail.com
www.github.com/kellykochanski

5.3 Contributing

If you wish to contribute a new feature or report a bug, welcome! See how to do this in CONTRIBUTING.md. Rescal-snow is distributed under the GNU GPL 3.0 license; all contributions must be made under this license or a later version.

6. Contributors

See AUTHORS.md.

Rescal-snow branched off of ReSCAL (v1.6) in 2016, and continues to use the ReSCAL backend for the cellular automaton and lattice gas models. This history is described in NEWS.md and the original code is available on branch rescal-1.6. Ongoing ReSCAL development is described at http://www.ipgp.fr/~rozier/rescal/rescal.html (the English version of this website is updated less regularly than the French). Our code is no longer easily compatible with ReSCAL, as we have removed features, unused code, and dependencies that were not related to wind-blown snow and reduced performance on high-performance computing systems. We are adopting a small fraction of new ReSCAL features on a case-by-case basis depending on their relevance to wind blown snow.

7. License

GNU GPL 3.0 or any later version. See LICENSE. SPDX-License-Identifier: GPL-3.0-or-later. This document was released from Lawrence Livermore National Laboratory under open source software release LLNL-CODE-785837; see NOTICE for details.