User Guide

The latest version of this document can be found at https://github.com/AvtechScientific/ASL/wiki/User-Guide.

Introduction

What is ASL

Advanced Simulation Library (ASL) is a free and open source multiphysics simulation software package. Its computational engine is based, among others, on the Lattice Boltzmann Methods and is written in OpenCL which enable extraordinarily efficient deployment on a variety of massively parallel architectures, ranging from inexpensive FPGAs, DSPs and GPUs up to heterogeneous clusters and supercomputers. The engine is hidden entirely behind C++ classes, so that no OpenCL knowledge is required from application programmers. ASL can be utilized to model various coupled physical and chemical phenomena and employed in a multitude of fields: computational fluid dynamics, virtual sensing, industrial process data validation and reconciliation, image-guided surgery, computer-aided engineering, high-performance scientific computing, etc..

Implemented features

See ASL features.

Getting help

Distributed documentation

ASL is distributed with a Developer Guide.

The Developer Guide can be generated using Doxygen locally from the source code's comments by enabling WITH_API_DOC option: cmake -DWITH_API_DOC=ON -G "Unix Makefiles" ../ASL. Documentation will be installed into share/doc/ASL/html subdirectory of the installation destination. Graphviz is recommended for better visualization of graphs.

On Debian/Ubuntu it can be installed like this: apt-get install doxygen graphviz

MathJax is used by Doxygen to display formulas. By default the Javascript is loaded from their CDN but it also can be installed locally (the MATHJAX_RELPATH in the Doxyfile has to be changed accordingly).

Getting started with ASL

Installation

Install cmake (>=3.0.2, BSD License) and the required libraries:
- OpenCL (=1.2 (2.0 supplies no C++ bindings), OpenCL Specification License)
- C++ bindings for OpenCL (=1.2 (2.0 supplies no C++ bindings), OpenCL Specification License)
- boost (>=1.55, Boost Software License)
- VTK (>=6.1, BSD License)
- optional: Matlab support with matio (>=1.5.2, BSD License)
- optional: API documentation with doxygen (preferably with graphviz)
Download and extract the ASL source code archive.
Create a build directory: mkdir build-asl; cd build-asl
Use cmake generator to produce Makefiles: cmake -G "Unix Makefiles" ../ASL or project files for your IDE (Visual Studio, Xcode, Eclipse, etc.): cmake -G "Visual Studio 10" ../ASL
Run make (as root if installing into default destination /usr/local): make install (installation destination can be changed: cmake -DCMAKE_INSTALL_PREFIX=/some/path/test/install ..).

Running an example

Go to examples: cd examples/flow/locomotive_in_tunnel
Copy the .stl input file: cp ../../../../ASL/examples/input_data/locomotive.stl .
Run: ./locomotive_in_tunnel. Optionally: change some parameters - ./locomotive_in_tunnel --dx 0.1 --dt 2 or write all of them into a file for later editing/reuse - ./locomotive_in_tunnel -g bigGrid.ini. List all available options - locomotive_in_tunnel -h.
Post-processing: see step by step example and the ParaView state file examples/input_data/locomotive_in_tunnel.pvsm.

Writing your own code using ASL

As long as the User Guide is not complete, the best way to get started with ASL is to learn the examples distributed in the examples directory and the API documentation, start with examples/flow/locomotive_in_tunnel.cc. For better understanding of the underlying concepts the Developer Guide can be studied.
ASL uses Semantic Versioning to make dependency management easy.
ASL installation supplies ASL.pc and ASLConfig.cmake files. To build your program using:
- pkg-config: launch c++ `pkg-config --cflags --libs ASL` -o locomotive_in_tunnel locomotive_in_tunnel.cc
- cmake: write a basic CMakeLists.txt file:

project(locomotive)
cmake_minimum_required(VERSION 3.0.2 FATAL_ERROR)
find_package(ASL 0.1.4 CONFIG REQUIRED)
set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} -std=c++11")
add_executable(locomotive_in_tunnel locomotive_in_tunnel.cc)
target_link_libraries(locomotive_in_tunnel PRIVATE ASL::aslnum ASL::aslvtk ASL::asl)

Fundamental data types

Implemented fluid models

Defining boundary conditions

Interfacing with other software, file formats

VTK/ParaView, MATLAB:

import file formats: .stl .vtp .vtk .vti .mnc .dcm
export file formats: .vti .mat

Utilities

Parameters Manager

ASL ParamatersManager and ApplicationParamatersManager classes facilitate the input of application parameters from the command line and/or from file. An application reads its configuration parameters from the command line or from the supplied parameters file (either through the command line option --parameters in short -p: multicomponent_flow -p BigTubesParams.ini or as a singleton command line parameter: multicomponent_flow HighComponent2Velocity.ini). It is recommended to use a separate folder with a relevant descriptive name for each set of simulation parameters.

Command line options

Example multicomponent_flow program, shown bellow, accepts a variety of command line options for operation, all of them can be listed using --help or, in short, -h option. Output of the multicomponent_flow --help command:

Usage: multicomponent_flow [PARAMETERS_FILE] [OPTION]...

Generic options:
  -h [ --help ]           Display this help and exit
  -v [ --version ]        Display version and exit
  -d [ --devices ]        Display all available devices and exit
  -p [ --parameters ] arg Path to the parameters file
  -g [ --generate ] arg   Generate default parameters file, write it and exit
  -c [ --check ]          Check parameters for consistency and exit

Parameters options:
  --platform arg (=Advanced Micro Devices, Inc.)
                                        Default computation platform
  --device arg (=AMD FX(tm)-6300 Six-Core Processor)
                                        Default computation device
  --dx arg (=0.00050000000000000001)    space step
  --dt arg (=1)                         time step
  --simulation_time arg (=0.002)        simulation time
  --output_interval arg (=0.0001)       output interval
  --nu arg (=2.4999999999999999e-08)    viscosity
  --tubeL arg (=0.25)                   tube's length
  --tubeD arg (=0.050000000000000003)   tube's diameter
  --pumpL arg (=0.025000000000000001)   pump's length
  --pumpD arg (=0.029999999999999999)   pump's diameter
  --component2_in_velocity arg (=0.080000000000000002)
                                        flow velocity in the component2 input
  --component1_in_velocity arg (=0.16)  flow velocity in the component1 input
  --component3_in_velocity arg (=0.10000000000000001)
                                        flow velocity in the component3 input

The options can be divided into two groups: generic options and configuration options. The first group displays useful auxiliary information about the software and the hardware deployed. The the second group sets the simulation configuration parameters. All the parameters with their descriptions, alternative names and default values are listed in the table above. Next, we describe some of the parameters in detail.

Parameters file

All the simulation configuration parameters mentioned in the previous section can be set within a parameters file which can be generated locomotive_in_tunnel -g BigGrid/BigGridParams.ini, edited and reused locomotive_in_tunnel BigGrid/BigGridParams.ini. Output files will be placed into the BigGrid directory. Descriptive names can help organize multiple parameters sets and respective simulation results. Parameter values passed directly in the command line override values in the file. A typical parameters file looks as follows:

# Parameters file
# Generated by locomotive_in_tunnel version 1.0

# Get the list of all available computation devices by running:
# `locomotive_in_tunnel -d`

# Default computation platform
platform = Advanced Micro Devices, Inc.

# Default computation device
device = AMD FX(tm)-6300 Six-Core Processor

# space step, [m]
dx = 0.08

# time step, [s]
dt = 1

# kinematic viscosity, [m^2/s]
nu = 0.001

# iterations number
iterations = 20001

Computation devices

The available computation devices, i.e. the computer hardware usable by an application, can be listed using --devices option. A typical output can look as follows:

pitot_tube_ice 0.1

Default computation device:
platform = Advanced Micro Devices, Inc.
device = AMD FX(tm)-6300 Six-Core Processor

List of all available platforms and their devices:
Platform: Advanced Micro Devices, Inc.
Number of devices: 2
	Tahiti
	AMD FX(tm)-6300 Six-Core Processor

This information is useful for performance benchmarking and comparison of different computer systems. By default first found device is used for computation; this can be changed either through the parameters file or from the command line: pitot_tube_ice --device 'AMD FX(tm)-6300 Six-Core Processor'