Ichnos is a general purpose particle tracking code. As such, Ichnos can trace virtual particles in velocity fields. The development of the code is heavily influenced by the projects that Ichnos was developed for, which is primarily particle tracking in groundwater flow fields. In particular, in groundwater flow fields calculated from finite element groundwater models. Yet, groundwater velocity fields from finite difference and finite volume codes can also be used. A key consideration during the development of the code is to handle simulations with multi-million velocity nodes. Therefore the code can be used with velocitiy fields that can be split across many processors.
A brief demonstration of the capabilities of this code can be found at our AGU 2020 poster.
Note that this is a continuation of a previous project IWFMtrack.
In particle tracking codes there are essentially two main functionalities. i) Tracing the particles in a velocity field. ii) Interpolating a velocity field. The code has been designed so that tracing functions are unaware of the details of the velocity field. To do so the code contains a velocity base class that communicates with the tracing class. Then each different type of field has to derive from the base velocity class and overwrite a few functions. The velocity field field can be split into 2 components. The positional information of the points where the velocity is known and the velocity itself. Each of those components are defined in based classes. The positional base class class XYZ is responsible to calculate the weight contribution of each velocity point in the field for a given particle position. Then it passes the weights to the Velocity class which then calculates the velocity value. Using this separation it is possible to combine different data structures in the code.
At the moment we provide two types of positional classes XYZ
- CLOUD
The CLOUD type assumes that the velocity information is defined into a cloud of points without any particular relation other that proximity between the nodes. - CLOUD GRAPH
Cloud graph type is very similar to cloud except that the velocity nodes are aware which velocity nodes are influential. - MESH2D
The MESH2D type assumes that the velocity is organized via a 2D mesh that is extruded in the vertical direction. Within the extruded 2D mesh the velocity can be defined at the element barycenters, which assumes constant velocity within the elements, or at the mesh nodes, or at the Mesh faces. In the latter case the interpolation is carried out using the Raviart–Thomas basis functions.
For the velocity there are two options:
- Transient/Steady state flow fields
- Stochastic flow fields (This is in an experimental stage)
- Random Walk (This is in an experimental stage)
Windows executables are available under the Bin folder. However, those executables may not contain the latest updates, fixes and new bugs.
Under the Bin folder there is a Dev folder which contains the latest build. You can check here which examples have been tested so far with the current development version.
Put under the same folder the exe and all the dlls. Make sure the antivirus is not blocking the execution. To verify that the code can run try the following under a powershell or command prompt.
ichnos.exe -v
For linux you have to compile the code. See the section below.
The wiki is the best source to get you started.
To build ichnos we use cmake. The code contains the required CMakeList.txt. However it is possible that it may need adjustments for each system.
Ichnos depends on a few libraries
- MPI. All mpi frameworks should work.
- Boost witn mpi support. Any relatively new version of boost is good. In the CMakeList.txt we require 1.58 but the code works with lower versions.
- CGAL Similarly any relatively recent version should work.
- HighFive. This is optional but speeds up the reading of large files and it is highly recommended.
Getting the dependencies right sometimes can be quite tricky. To build Ichnos we have used three options for different systems.
- vcpkg is probably the easiest method to build the dependencies. It has always worked under windows without issues. Under linux can work but not without issues.
- Spack Using spack is probably the best option for linux, yet is a bit more involved compared to the vcpkg. There is more info about spack in the next section
- Build everything That requires some experience and it is recommended on systems without administration privileges, e.g clusters.
All that is needed is to pass the following argument
-DCMAKE_TOOLCHAIN_FILE=path\to\vcpkg\scripts\buildsystems\vcpkg.cmake -DUSEHF=True
If HighFive is not available then set -DUSEHF=False
The following is just a guide which at times is not working and requires workarounds.
First create an environment that we name it ichnos
spack env create ichnos
and make it active
spack env activate ichnos
Next we are going to install cmake. Any version should work however I'm specifying here 3.9.4 because this has already been built in other spack environments.
spack install cmake@3.9.4 target=x86_64
Now the command spack find should find that the cmake is installed and the cmake --version should return the version information.
Next we will install openmpi. The spack info openmpi will return the available openmpi versions, while at the top specifies which one is the prefered. At the time of writing this that was the 3.1.4 so we build it as
spack install openmpi@3.1.4 target=x86_64
Usually clusters provide mpi frameworks and it is always a good practice to use these. To instruct Spack to use an external package one has to create a packages.yaml file with content similar to the following:
packages:
mpi:
buildable: False
openmpi:
modules:
openmpi@4.0.1: openmpi/4.0.1
buildable: False
It is important to set for the external packages the buildable flag as false.
Note: It is possible to build your own mpi via spack however there is the chance that you get errors during runtime that mpi is linked with a different version of mpi
The next piece ichnos needs is boost. I'll install 1.69 as this is the one already exists from previous projects.
spack install boost@1.69.0+mpi ^openmpi@3.1.4 target=x86_64
CGAL is the next library that is required by ichnos. CGAL depends on boost so we will specify that we want to build cgal using the boost version we just installed
spack install cgal@4.13 ^boost@1.69.0+mpi ^openmpi@3.1.4 target=x86_64
Sometimes cgal failed to get build because the mprf failed to apply a patch. One way to bypass this is by using a different version of mpfr
spack install cgal@4.13 ^boost@1.69.0+mpi ^openmpi@3.1.4 ^mpfr@4.0.0
The last library Highfive is optional.
spack install highfive target=x86_64
Assuming that the current directory is ../ichnos_code/ where the CMakeLists.txt file is, create a folder, get into the folder and run cmake as
mkdir build
cd build
cmake ..
If cmake finds the wrong boost version e.g the one under /usr/ for example then passing the following during cmake might help
cmake -DUSEHF=True \
-DBoost_NO_BOOST_CMAKE=TRUE \
-DBoost_NO_SYSTEM_PATHS=TRUE \
-DBOOST_ROOT:PATHNAME=/path/to/spack/var/spack/environments/ichnos/.spack-env/view/ ..
see more.
Ichnos reads the inputs from ascii or HDF5 files and writes the outputs to ascii or HDF5 files as well.
To run Ichnos one need to prepare two configuration files as well as a number of other input files that descibe the velocity fields and the domain. You can run the code with the following options:
- Read the version of the executable
ichnos.exe -v
- Get help options
ichnos.exe -h
- Run the code
ichnos.exe -c config.ini
It depends on what you want to say
The Discussion section is the best place to ask questions/clarifications regarding the use of Ichnos.
Any issues with the code should be reported at Issues section.
For other information you can reach us via email