flow123d / bparser

A C++ library for parsing expressions with Python syntax and using SIMD for repetitive evaluation. Amortization of the interpreter overhead leads to nearly peak CPU performance..

Flow123d ·

Processes in Fractured Media

Flow123d is a simulator of underground water flow, transport, and mechanical processes in fractured porous media. Novelty of this software is support of computations on complex meshes consisting of simplicial elements of different dimensions. Therefore we can combine continuum models and discrete fracture network models. For more information see the project pages: flow123d.github.io.

Getting started

Please refer to a User Guide and Input Reference manual available at our official website where there is a entire section dedicated to this topic. You can find step-by-step tutorial explaining geometries, yaml input files and more. Below you can see a result from the tutorial problem.

Installation

You have several options when it comes to installation. You can use our prebuilt Docker images or build Flow123d from the source (requires a moderate experience with Linux OS).

For detailed instructions, see the installation guide.

Developers

Build

Two step build:

     host> bin/fterm     # start the docker developing container
container> make all      # produce "build_tree/bin/flow123d"
container> bin/flow123d  # lunch the simulator using a simple wrapper script

That would start the debug docker image and build the debug version of the simulator. For the release (optimized) version run:

bin/fterm rel
make all

For details see installation guide or the manual.

Troubleshooting

• When problem occurs during the compilation process it may be due to a leftover files in a build folder. Cleaning this directory can solve this issue. You can either remove build-<branch> folder (the folder is located one level above repository root) via make clean-all, which removes build folders and also remove any symlinks.
  To clean all the build folders manually run rm -rf ../build-* while in a repository root.
  Running rm -rf can quite easily cause a lot of damage, double check that you're in a correct folder.

• The build tools may fail if the root path contains folders with spaces.

• During an installation under Windows, some scenarios can cause problems. Please refer to an installation guide for a Docker Toolbox. You can also check out Troubleshooting page where the most common error are described and solved.

Building the reference manual

The reference manual can be built by while in docker container

make ref-doc

To copy out reference manual from docker use command docker cp.

Singularity

Singularity is a container system targeting HPC applications. Singularity containers can be created from the docker images and in contrast to the docker one is not allowed to modify system of running containers.

For large images may be necessary set temp directory.

export SINGULARITY_TMPDIR="/some_absolute_path/tmp"

Run simulator in singularity container

singularity exec docker://flow123d/3.1.0 flow123d simulation.yaml

Parallel run, mpiexec out of the image

module add mpich-3.0.2-gcc
mpiexec -host host1,host2 -np 4 singularity exec docker://flow123d/3.1.0 flow123d simulation.yaml

Build

     host> git clone https://github.com/flow123d/flow123d.git # clone flow123d repository
     host> singularity shell -B flow123d/:/flow123d docker://flow123d/flow-dev-gnu-rel:3.1.0 # starts developing container
container> cd /flow123d
container> make all # produce "build_tree/bin/flow123d"
container> bin/flow123d  # lunch the simulator

Docker images

Hosted on dockerhub under organisation flow123d.

production images

tagged by the release version (e.g. 3.1.0)

• flow123-gnu : based on gnu libraries and tools
• flow123-intel : based on intel libraries (intelmpi, mkl, intel compilers)

alfa images

built by CI, tagged by {branch}-{commit}

• ci-gnu
• ci-intel

bparser's Issues

More general SIMD support

See Vectorization blog for the problematic.

Use some library to support different kind of vectorization instructions namely AVX2 and AVX512 and possibly some new.
Possibilities:

• simple wrapper that is part of the blog
• vectorclass
• Uniform Multicore Environment

Support for single memory block operations

• support one big arena allocation containing data and processors from more Parser instances
• implement sort of Parser manager operating on single continuous block of memory optimizing cache
• will be created in GenricAssembly and used by all computation objects used during assembly:
  field caches, FieldFE FeValues, BParser processors, ...

Finish parser

• finish Array class to represent array structure of the scalar expressions

  • elementwise operations
  • mat mult
  • indexing, splicing
  • broadcasting, composing
  • user API

• basic spirit grammar

• AST

• conversion of AST to processor

• chained relational operators

• grammar rules for: indexing, variadic functions, composing, mat mult

• translate variadic functions and mat mult to array operations

• speed tests

• safe ScalarNode

• default workspace for variables

• CMake

• update Readme

Allow to have multiple results.

• allow having variable on the LHS
• in agreement with current concept, where final result is an implicit variable

Documentation

Document used expression syntax.
Document library usage.
Briefly document implementation.

Flow123d operations

• vector and tensor composition and indexing

  • vector constructor grammar
  • vector constructor execution
  • vector slicing grammar
  • vector slicing execution

• if then else expression, var = <true_expr> if <condition> else <false_expr>

• Parser copy constructor ??

• remove printout (call print_in_dot) in Parser::compile

Improve error reporting.

• store positions of the AST nodes in the input formula string.
• Throw an exception in array functions, catch in ast::make_array.

Rethink syntax for automatic copy and allo it for the result.

• simplify parser interface
• simplify resolution in create_xyz_node possibly use template directly
• allow copy of the result, check if it is not doe anyway
• rename BParser::run to eval() , return result variable
• define Variable class in public interface

Chained comparisons

Implement chained comparisons: 0 < x < 1.

The chained expression

LEFT_OP rel_left MID_OP rel_right RIGHT_OP

is equivalent to:

(LEFT_OP rel_left MID_OP) and (MID_OP rel_right RIGHT_OP)

but the MID_OP has to be evaluated just once.

To implement this we need special support in transformation mechanism from AST to the expression DAG
or we need reliable optimization to eliminate duplicate evaluation.

See branch JB_chained.

vector and matrix functions

dot(a, b)
det(A) - determinent of matrix
norm(v) - l2 norm of vector or matrix
norm(v, exp) - lp norm
norm_max(v) ..
inv(A)
eye(n)
zero(n,m)
diag_mat(vec)
diag(mat)

reduction operations: sum, prod, mean, ...

Complex processor test

• framework for tests using more complex expressions
• speed test for different expressions

Refactor and document.

• Improve naming of types and functions, eg. ScalarNode -> ScalarOperation,
• Document at least classes.
• Refactor array_ast_interface
• consider splitting some files.
• Tutorial with usecases of different complexity.
• Appropriate improvement of the API.

Eliminate const expressions

• perform operations on constants during 'compilation'

vectorize bool operations

In order to vectorize opeartions resulting into bool values we have to:

1. reprezent bool values as masks (DONE)
2. use vector functions to produce these masks

See:
masking

Related to #1

STL conforming arena allocator

Possibly: https://github.com/Kubiyak/ArenaAlloc