97 lines
4.3 KiB
Markdown
97 lines
4.3 KiB
Markdown
|
|
|
|
# Astaroth - A Multi-GPU library for generic stencil computations
|
|
|
|
[Wiki](https://bitbucket.org/jpekkila/astaroth/wiki/Home) | [Issue Tracker](https://bitbucket.org/jpekkila/astaroth/issues?status=new&status=open) | [Contributing](https://bitbucket.org/jpekkila/astaroth/src/master/CONTRIBUTING.md) | [Licence](https://bitbucket.org/jpekkila/astaroth/src/master/LICENCE.txt)
|
|
|
|
Astaroth is a multi-GPU library for three-dimensional stencil computations. It is designed especially for performing high-order stencil
|
|
computations in structured grids, where several coupled fields are updated each time step. Astaroth consists of a multi-GPU and single-GPU
|
|
APIs and provides a domain-specific language for translating high-level descriptions of stencil computations into efficient GPU code. This
|
|
makes Astaroth especially suitable for multiphysics simulations.
|
|
|
|
Astaroth is licenced under the terms of the GNU General Public Licence, version 3, or later
|
|
(see [LICENCE.txt](https://bitbucket.org/miikkavaisala/astaroth-code/src/master/astaroth_2.0/LICENCE.txt)). For contributing guidelines,
|
|
see [Contributing](https://bitbucket.org/jpekkila/astaroth/src/master/CONTRIBUTING.md).
|
|
|
|
|
|
## System Requirements
|
|
* An NVIDIA GPU with support for compute capability 3.0 or higher (Kepler architecture or newer)
|
|
|
|
## Dependencies
|
|
Relative recent versions of
|
|
|
|
`gcc cmake cuda flex bison`.
|
|
|
|
## Building
|
|
|
|
In the base astaroth directory, run
|
|
|
|
0. `mkdir build`
|
|
0. `cd build`
|
|
0. `cmake ..`
|
|
0. `make -j`
|
|
|
|
> **Optional:** Documentation can be generated with `doxygen doxyfile` (requires Doxygen). The
|
|
generated documentation can be found in `doc/doxygen`.
|
|
|
|
> **Tip:** The library is configured by passing [options](#cmake-options) to CMake with `-D[option]=[ON|OFF]`.
|
|
For example, double precision can be enabled by calling `cmake -DBUILD_DOUBLE_PRECISION=ON ..`.
|
|
See [CMakeLists.txt](https://bitbucket.org/jpekkila/astaroth/src/master/CMakeLists.txt) for an up-to-date list of options.
|
|
|
|
> **Note:** CMake will inform you if there are missing dependencies.
|
|
|
|
## [CMake options](#cmake-options)
|
|
|
|
| Option | Description | Default |
|
|
|--------|-------------|---------|
|
|
| BUILD_DEBUG | Builds Astaroth with extensive error checking | OFF |
|
|
| BUILD_STANDALONE | Builds a standalone library for testing, benchmarking and simulation | ON |
|
|
| BUILD_UTILS | Builds a generic utility library (WIP replacement for BUILD_STANDALONE) | ON |
|
|
| BUILD_RT_VISUALIZATION | Builds the real-time visualization module | OFF |
|
|
| BUILD_DOUBLE_PRECISION | Generates double precision code | OFF |
|
|
| MULTIGPU_ENABLED | Enables Astaroth to use multiple GPUs on a single node | ON |
|
|
| MPI_ENABLED | Enables additional functions for MPI communciation | OFF |
|
|
| DSL_MODULE_DIR | Defines the directory to be scanned when looking for DSL files | `astaroth/acc/mhd_solver` |
|
|
|
|
|
|
## Standalone module
|
|
|
|
|
|
```Bash
|
|
Usage: ./ac_run [options]
|
|
--help | -h: Prints this help.
|
|
--test | -t: Runs autotests.
|
|
--benchmark | -b: Runs benchmarks.
|
|
--simulate | -s: Runs the simulation.
|
|
--render | -r: Runs the real-time renderer.
|
|
--config | -c: Uses the config file given after this flag instead of the default.
|
|
```
|
|
|
|
See `analysis/python/` directory of existing data visualization and analysis scripts.
|
|
|
|
## Interface
|
|
|
|
* `astaroth/include/astaroth.h`: Legacy interface for backwards compatibility and quick testing.
|
|
* `astaroth/include/astaroth_node.h`: Multi-GPU interface (single node).
|
|
* `astaroth/include/astaroth_device.h`: Single-GPU interface.
|
|
* `astaroth/src/utils`: Utility library for host-side memory allocations, verification and other tasks.
|
|
|
|
## FAQ
|
|
|
|
Can I use the code even if I don't make my changes public?
|
|
|
|
> [GPL](https://bitbucket.org/jpekkila/astaroth/src/master/LICENCE.txt) requires only that if you release a binary based on Astaroth to the
|
|
public, then you should also release the source code for it. In private you can do whatever you want (secret forks, secret collaborations,
|
|
etc).
|
|
|
|
How do I compile with MPI support?
|
|
|
|
> MPI implementation for Astaroth is still work in progress, these commands are for testing only.
|
|
Invoke CMake with `cmake -DMPI_ENABLED=ON -DBUILD_MPI_TEST=ON -DCMAKE_CXX_COMPILER=$(which mpicxx) ..`.
|
|
Otherwise the build steps are the same. Run with `mpirun -np 4 ./mpitest`.
|
|
|
|
How do I contribute?
|
|
|
|
> See [Contributing](https://bitbucket.org/jpekkila/astaroth/src/master/CONTRIBUTING.md).
|
|
|