User Guide
The latest version of this document can be found at https://github.com/AvtechScientific/ASL/wiki/User-Guide.
Advanced Simulation Library (ASL) is an open source multiphysics simulation software package and a tool for solving Partial Differential Equations. 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 the application programmers. ASL can be utilized to model various coupled physical and chemical phenomena, especially in the field of CFD.
See ASL features.
The User Guide can be converted from the Markdown into other formats like html, pdf, odt, etc., using Pandoc: pandoc User-Guide.md -o User-Guide.html
ASL is distributed with a Developer Guide that can be found in the doc directory.
The Developer Guide can be generated using Doxygen locally from the source code's comments by executing doxygen from within the doc/Developer-Guide directory of the ASL distribution. Graphviz is needed as well.
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).
- OpenCL
- C++ bindings for OpenCL
- boost
- VTK
- optional: matio
CMake is used to build the project.
Installation destination can be changed:
cmake -DCMAKE_INSTALL_PREFIX=/some/path/test/install ..
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 test/testPhysics directory. For better understanding of the underlying concepts the developer guide can be studied. Some examples require input files (like .stl files), they can be found in test/input_data. They were obtained from GrabCAD and are subject to their Terms of Service.
- All file formats supported by VTK (.vti, .stl, etc..)
- MATLAB (export)
ParamatersManager class facilitates the input of application paramters from the command line and/or from file.
An application reads its configuration parameters from the command line or from the parameters.ini file that it assumes to reside in the working folder. The working folder, which is where all the file input and output occurs, can be defined in three ways: (1) through the command line option -folder; (2) as a singleton command line parameter; or (3) a default value which is the folder Default under the current directory of execution. It is recommended to use a separate folder with a relevant descriptive name for each set of simulation parameters.
In addition, the computation device must be defined as described later on.
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 [WORKING_FOLDER] [OPTION]...
Generic options:
-h [ --help ] display this help and exit
-v [ --version ] display version and exit
-d [ --devices ] display available devices and exit
-f [ --folder ] arg (=Default) path to the working folder that contains
configuration file - parameters.ini
-c [ --check ] check configuration for consistency and exit
Configuration options:
--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
--oil_in_velocity arg (=0.080000000000000002)
flow velocity in the oil input
--water_in_velocity arg (=0.16) flow velocity in the water input
--gas_in_velocity arg (=0.10000000000000001)
flow velocity in the gas 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.
All the simulation configuration parameters mentioned in previous section can be set within a file named parameters.ini located in the working folder. Parameter values passed directly in the command line override values in the file. A typical parameters.ini file looks as follows:
# Brain Shift Simulator
# All lengths and positions values are in mm
# mu0 is the instantaneous shear modulus in undeformed state [Pa]
# Files
skull_file = skull.vti
brain_file = brain.vti
# Physics
g = -9.8 -1 0
# Numerics
dt = 1e-5
simulation_time = 2e-3
output_interval = 1e-4
# Media
shear_modulus = 1.e6
bulk_modulus = 2.5e6
rho = 900
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
Platform: Advanced Micro Devices, Inc.
Number of devices: 2
Tahiti
AMD FX(tm)-6300 Six-Core Processor
Default device: Advanced Micro Devices, Inc., Tahiti
This information is useful for performance benchmarking and comparison of different computer systems. In addition, it can be used to define the default platform and default device in the asl.ini.
ASL is configured through asl.ini file which has to reside in the same folder as the application's executable file. asl.ini has only two configuration parameters: platform of the device to be used by default for computation, device to be used by default for computation. If desired platform and device are not detected the user will be warned and the automatically found device will be used. Below one can find a typical asl.ini file.
# ASL configuration file
platform = Advanced Micro Devices, Inc.
device = AMD FX(tm)-6300 Six-Core Processor
Post-processing can be done using ParaView.
Proper paths for the following files need to be provided on state file loading:
- locomotive_in_tunnel_*.vti - VTK output files.
- locomotive.stl - surface geometry file (is distributed in the
test/input_data).
Sample state file: locomotive_in_tunnel.pvsm (tested on Linux, ParaView 4.0.1 64-bit).
