From 785230053d4b9825d89ec3a4c09660b25e1c2b04 Mon Sep 17 00:00:00 2001 From: jpekkila Date: Mon, 13 Jan 2020 15:27:24 +0000 Subject: [PATCH] Rewrote README.md --- README.md | 226 +++++++++++++++++++----------------------------------- 1 file changed, 77 insertions(+), 149 deletions(-) diff --git a/README.md b/README.md index 023b55d..c94d3c1 100644 --- a/README.md +++ b/README.md @@ -2,169 +2,97 @@ # Astaroth - A Multi-GPU library for generic stencil computations -Astaroth is a single-node multi-GPU library for multiphysics and other problems, which involve stencil computations in a discrete mesh. It's 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)). Astaroth ships with a domain-specific language that can be used to translate high-level representations of various stencil operations into efficient CUDA kernels. +[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) -## System requirements +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. -NVIDIA GPU with >= 3.0 compute capability. See https://en.wikipedia.org/wiki/CUDA#GPUs_supported. - -## Building (3rd party libraries for real-time visualization) - -1. `cd 3rdparty` -1. `./setup_dependencies.sh` Note: this may take some time. - -## Building - -There are two ways to build the code as instructed below. - -If you encounter issues, recheck that the 3rd party libraries were successfully built during the previous step. +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). -### New approach +## 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 + +| 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` | -1. `mkdir whatever && cd whatever # Sourcing not required anymore` - -1. `cmake -DDSL_MODULE_DIR=acc/mhd_solver .. && make -j` - -1. `./ac_run -t ../config/astaroth.conf` +## Standalone module -### Method I: In the code directory (DEPRECATED. REVISE.) - -1. `cd build/` -1. `cmake -DDOUBLE_PRECISION=OFF -DBUILD_DEBUG=OFF ..` (Use `cmake -D CMAKE_C_COMPILER=icc -D CMAKE_CXX_COMPILER=icpc -DDOUBLE_PRECISION=OFF -DBUILD_DEBUG=OFF ..` if compiling on TIARA) -1. `../scripts/compile_acc.sh && make -j` -1. `./ac_run ` - -Edit `config/astaroth.conf` to change the numerical setup. - -### Method II: With a script in a custom build directory (DEPRECATED. REVISE.) - -1. `source sourceme.sh` to add relevant directories to the `PATH` -1. `ac_mkbuilddir.sh -b my_build_dir/` to set up a custom build directory. There are also other options available. See `ac_mkbuilddir.sh -h` for more. -1. `compile_acc.sh` to generate kernels from the Domain Specific Language -1. `cd my_build_dir/` -1. `make -j` -1. `./ac_run ` - -Edit `my_build_dir/astaroth.conf` to change the numerical setup. - -### Available options - -- `-s` simulation -- `-b` benchmark -- `-t` automated test - -By default, the program does a real-time visualization of the simulation domain. The camera and the initial conditions can be controller by `arrow keys`, `pgup`, `pgdown` and `spacebar`. - -## Visualization - -See `analysis/python/` directory of existing data visualization and analysis scripts. - -## Generating documentation - -Run `doxygen doxyfile` in astaroth_2.0 directory. The generated files can be found in `doc/doxygen`. The main page of the documentation will be at `dox/doxygen/astaroth_doc_html/index.html`. - -## Formatting - -If you have clang-format, you may run `scripts/fix_style.sh`. This script will recursively fix style of all the source files down from the current working directory. The script will ask for a confirmation before making any changes. - -## Directory structure -TODO - -## Contributing - -0. **Do not break existing functionality.** Do not modify the interface functions declared in astaroth.h and device.cuh in any way. Bug fixes are exceptions. If you need new functionality, create a new function. - -0. **Do not rename or redefine variables or constants declared in astaroth.h** without consulting everyone involved with the project. - -0. **Ensure that the code compiles and the automated tests pass** by running `./ac_run -t` before pushing changes to master. If you want to implement a feature that consists of multiple commits, see Managing feature branches below. - -### Managing feature branches - -0. Ensure that you're on the latest version of master. `git checkout master && git pull` - -0. Create a feature branch with `git checkout -b `, f.ex. `git checkout -b forcingtests_2019-01-01` - -0. Do your commits in that branch until your new feature works - -0. Merge master with your feature branch `git merge master` - -0. Resolve the conflicts and test that the code compiles and still works by running `./ac_run -t` - -0. If everything is OK, commit your final changes to the feature branch and merge it to master `git commit && git checkout master && git merge && git push` - -0. Unless you really have to keep your feature branch around for historical/other reasons, remove it from remote by calling `git push origin --delete ` - -A flowchart is available at [doc/commitflowchart.png](https://bitbucket.org/jpekkila/astaroth/src/2d91df19dcb3/doc/commitflowchart.png?at=master). - -### About branches in general - -* Unused branches should not kept around after merging them into master in order to avoid cluttering the repository. - -* `git branch -a --merged` shows a list of branches that have been merged to master and are likely not needed any more. - -* `git push origin --delete ` deletes a remote branch while `git branch -d ` deletes a local branch - -* If you think that you have messed up and lost work, run `git reflog` which lists the latests commits. All work that has been committed should be accessible with the hashes listed by this command with `git checkout `. - -## Coding style. - -### In a nutshell -- Use [K&R indentation style](https://en.wikipedia.org/wiki/Indentation_style#K&R_style) and 4 space tabs. -- Line width is 100 characters -- Start function names after a linebreak in source files. -- [Be generous with `const` type qualifiers](https://isocpp.org/wiki/faq/const-correctness). -- When in doubt, see [Google C++ Style Guide](https://google.github.io/styleguide/cppguide.html). - -### Header example: -```cpp -// Licence notice and doxygen description here -#pragma once -#include "avoid_including_headers_here.h" - -/** Doxygen comments */ -void globalFunction(void); +```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. -### Source example: -```cpp -#include "parent_header.h" +## Interface -#include +* `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. -#include "other_headers.h" -#include "more_headers.h" +## FAQ -typedef struct { - int data; -} SomeStruct; +Can I use the code even if I don't make my changes public? -static inline int small_function(const SomeStruct& stuff) { return stuff.data; } - -// Pass constant structs always by reference (&) and use const type qualifier. -// Modified structs are always passed as pointers (*), never as references. -// Constant parameters should be on the left-hand side, while non-consts go to the right. -static void -local_function(const SomeStruct& constant_struct, SomeStruct* modified_struct) -{ - modified_struct->data = constant_struct.data; -} - -void -globalFunction(void) -{ - return; -} -``` -## TIARA cluster compilation notes - -Modules used when compiling the code on TIARA cluster. - - * cmake/3.9.5 - * gcc/8.3.0 - * cuda/10.1 +> [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). +