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 hardware accelerated multiphysics simulation platform (and an extensible general purpose tool for solving Partial Differential Equations). Its computational engine is written in OpenCL and utilizes matrix-free solution techniques which enable extraordinarily high performance, memory efficiency and deployability 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 simple C++ classes, so that no OpenCL knowledge is required from application programmers. Mesh-free, immersed boundary approach allows one to move from CAD directly to simulation drastically reducing pre-processing efforts and amount of potential errors. ASL can be used 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, design space exploration, crystallography, 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, OpenCL Specification License); open or closed source implementation, see deployment information
- boost (>=1.53, 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
Download geometry file locomotive.stl from the ASL input data page.
Run: ./asl-locomotive --input locomotive.stl
Optionally: change parameters ./asl-locomotive --input locomotive.stl --dx 1 --dt 2 or write all of them into a file for later editing/reuse - ./asl-locomotive -g bigGrid.ini. List all available options - ./asl-locomotive -h.
Post-processing: see step by step example and locomotive.pvsm - the ParaView state file.

Writing your own code using ASL

Take a look at examples and the API documentation, start with examples/flow/locomotive.cc
ASL installation supplies ASL.pc and ASLConfig.cmake files. To build your program using:

pkg-config: c++ `pkg-config --cflags --libs ASL` -std=c++11 -o flow flow.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 locomotive.cc)
target_link_libraries(locomotive 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 facilitates the input of application parameters from command line and/or from file. An application read its configuration parameters from command line or from the file supplied as parameter (i.e 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 relevant descriptive name for each set of simulation parameters.

Command line options

Example multicomponent_flow program, shown below, 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 -g BigGrid/BigGridParams.ini, edited and reused locomotive 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 version 1.0

# Get the list of all available computation devices by running:
# `locomotive -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 looks 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'