How to use the AMITEX_FFTP Apptainer image ?
Prerequisites
- Have Apptainer or Docker installed (installation guide)
- Have downloaded the amitex_fftp image available here
- Have downloaded the input files available here
For more information on Apptainer containers, please look at this page or refer to this tutorial to have a quick look at Apptainer’s main commands.
Create a directory containing the amitex_fftp.sif image and the archive of the input files. Move into this directory and extract the archive as follows:
tar -xzf amitex-tutorial-inputs.tar.gz # Extracts the contents of the archive.One-line command
For those in a hurry, here is how to launch an Amitex_FFTP computation:
apptainer exec amitex_fftp.sif mpirun -np <N> amitex_fftp <args>Introduction
Amitex_FFTP is a massively parallel simulation code built around the MPI standard, allowing the computational workload to be distributed across multiple processes. There are two ways to run the containerized code in parallel:
- MPI embedded in the container => guaranteed to work, but limited to a single machine (a single node)
- Hybrid MPI using the host machine’s MPI => works across multiple nodes but may introduce compatibility issues.
Local simulation (embedded MPI)
apptainer exec amitex_fftp.sif mpirun amitex_fftp -nm concrete.vtk -m material.xml -c loading.xml -a algorithm.xml -s outNote that the command first launches apptainer, which then executes mpirun amitex_fftp <args> inside the container.
Cluster simulation (hybrid MPI)
Launch with the SLURM scheduler (recommended)
Example of a minimal launch script job.sh:
#!/bin/bash
#SBATCH --job-name=test_amitex
#SBATCH --output=slurm-%j.out
#SBATCH --error=slurm-%j.err
#SBATCH --ntasks=12
#SBATCH --time=00:05:00
srun apptainer exec amitex_fftp.sif amitex_fftp -nm concrete.vtk -m material.xml -c loading.xml -a algorithm.xml -s outThe computation can then be launched with the command:
sbatch job.shLaunch without a scheduler
mpirun -np <N> apptainer exec amitex_fftp.sif amitex_fftp -nm concrete.vtk -m material.xml -c loading.xml -a algorithm.xml -s out*The mpirun command must come from OpenMPI 4 for this to work.
Visualizing the results
Generate strain curves with Gnuplot:
apptainer exec amitex_fftp.sif gnuplot < plot.gpThis creates concrete_stress_strain.svg, which can then be displayed with a standard image viewer.
To visualize .vtk files, Paraview must be used. We provide a Paraview container
here. Once the Paraview container has been downloaded, the microstructure concrete.vtk can be visualized as follows:
apptainer run paraview.sif concrete.vtk
# Then in the graphical interface click "Apply" in the left Properties panel
# Then in the top menu bar select "MaterialId" in the drop-down menu instead of "Solid Color".
# Then in the top menu bar select "Surface" in the drop-down menu instead of "Outline".(Advanced) User-defined material behavior law
UMAT Behaviors
It is possible to define custom material behavior laws using a UMAT-compatible procedure. We will look at an example of a user-defined material behavior law used with AMITEX_FFTP. You can retrieve the example provided in the container with:
cp -r /gnu/store/$(ls /gnu/store | grep amitex_fftp)/cas_tests/comportements/polyxCC/comportement_umat .
chmod -R u+w comportement_umatThe provided example is already compiled, so you can start by cleaning the comportement_umat directory:
cd comportement_umat
apptainer exec ../amitex_fftp.sif make cleanYou can now implement the desired behavior by modifying the files with your preferred text editor. Then, recompile the behavior law with:
apptainer exec ../amitex_fftp.sif make
cd ..This creates comportement_umat/libUmatAmitex.so. Next, you need to modify material.xml to call this new behavior law by replacing, for example <Material numM="2" Lib="" Law="elasiso"> [...] </Material> with:
<Material numM="2" Lib="comportement_umat/libUmatAmitex.so" Law="umatBCCHPP" >
<Coeff Index="1" Type="Constant" Value="236.412E3"/>
<Coeff Index="2" Type="Constant" Value="0.35"/>
<Coeff Index="3" Type="Constant" Value="275.2E3"/>
<Coeff Index="4" Type="Constant" Value="112.4E3"/>
<Coeff Index="5" Type="Constant" Value="87.56E3"/>
<Coeff Index="6" Type="Constant" Value="363."/>
<Coeff Index="7" Type="Constant" Value="0."/>
<Coeff Index="8" Type="Constant" Value="1000."/>
<Coeff Index="9" Type="Constant" Value="10e-6"/>
<Coeff Index="10" Type="Constant" Value="1e11"/>
<Coeff Index="11" Type="Constant" Value="2.481e-7"/>
<Coeff Index="12" Type="Constant" Value="100"/>
<Coeff Index="13" Type="Constant" Value="3."/>
<Coeff Index="14" Type="Constant" Value="2.e-6"/>
<Coeff Index="15" Type="Constant" Value="0.84"/>
<Coeff Index="16" Type="Constant" Value="1e5"/>
<Coeff Index="17" Type="Constant" Value="1e5"/>
<Coeff Index="18" Type="Constant" Value="1e-6"/>
<Coeff Index="19" Type="Constant" Value="50"/>
<Coeff Index="20" Type="Constant" Value="0"/>
<Coeff Index="21" Type="Constant" Value="0.3"/>
<Coeff Index="22" Type="Constant" Value="1."/>
<Coeff Index="23" Type="Constant" Value="5.e-4"/>
<Coeff Index="24" Type="Constant" Value="50"/>
<Coeff Index="25" Type="Constant" Value="0."/>
<Coeff Index="26" Type="Constant" Value="0."/>
<Coeff Index="27" Type="Constant" Value="0."/>
<IntVar Index="1" Type="Constant" Value="0."/>
<IntVar Index="2" Type="Constant" Value="0."/>
<IntVar Index="3" Type="Constant" Value="0."/>
<IntVar Index="4" Type="Constant" Value="0."/>
<IntVar Index="5" Type="Constant" Value="0."/>
<IntVar Index="6" Type="Constant" Value="0."/>
<IntVar Index="7" Type="Constant" Value="0."/>
<IntVar Index="8" Type="Constant" Value="0."/>
<IntVar Index="9" Type="Constant" Value="0."/>
<IntVar Index="10" Type="Constant" Value="0."/>
<IntVar Index="11" Type="Constant" Value="0."/>
<IntVar Index="12" Type="Constant" Value="0."/>
<IntVar Index="13" Type="Constant" Value="0."/>
<IntVar Index="14" Type="Constant" Value="0."/>
<IntVar Index="15" Type="Constant" Value="0."/>
<IntVar Index="16" Type="Constant" Value="0."/>
<IntVar Index="17" Type="Constant" Value="0."/>
<IntVar Index="18" Type="Constant" Value="0."/>
<IntVar Index="19" Type="Constant" Value="0."/>
<IntVar Index="20" Type="Constant" Value="0."/>
<IntVar Index="21" Type="Constant" Value="0."/>
<IntVar Index="22" Type="Constant" Value="0."/>
<IntVar Index="23" Type="Constant" Value="0."/>
<IntVar Index="24" Type="Constant" Value="0."/>
<IntVar Index="25" Type="Constant" Value="0."/>
<IntVar Index="26" Type="Constant" Value="0."/>
<IntVar Index="27" Type="Constant" Value="0."/>
<IntVar Index="28" Type="Constant" Value="0."/>
<IntVar Index="29" Type="Constant" Value="0."/>
<IntVar Index="30" Type="Constant" Value="0."/>
<IntVar Index="31" Type="Constant" Value="0."/>
<IntVar Index="32" Type="Constant" Value="0."/>
<IntVar Index="33" Type="Constant" Value="0."/>
<IntVar Index="34" Type="Constant" Value="0."/>
<IntVar Index="35" Type="Constant" Value="0."/>
<IntVar Index="36" Type="Constant" Value="0."/>
<IntVar Index="37" Type="Constant" Value="0."/>
<IntVar Index="38" Type="Constant" Value="0."/>
<IntVar Index="39" Type="Constant" Value="0."/>
<IntVar Index="40" Type="Constant" Value="0."/>
<IntVar Index="41" Type="Constant" Value="0."/>
<IntVar Index="42" Type="Constant" Value="0."/>
<IntVar Index="43" Type="Constant" Value="0."/>
<IntVar Index="44" Type="Constant" Value="0."/>
<IntVar Index="45" Type="Constant" Value="0."/>
<IntVar Index="46" Type="Constant" Value="0."/>
<IntVar Index="47" Type="Constant" Value="0."/>
<IntVar Index="48" Type="Constant" Value="0."/>
<IntVar Index="49" Type="Constant" Value="0."/>
</Material>You can now run the computation with the new behavior law, after removing <Loading Tag="2"> [...] </Loading> from loading.xml, which does not work in this example:
apptainer exec amitex_fftp.sif mpirun amitex_fftp -nm concrete.vtk -m material.xml -c loading.xml -a algorithm.xml -s outMFRONT Behaviors
It is also possible to define custom material behavior laws using mfront. Here we present an example of a material behavior defined with mfront, then used with AMITEX_FFTP. The first step is to generate the dynamic library containing the UMAT function:
apptainer exec amitex_fftp.sif mfront --obuild --interface=umat Mazars.mfrontThis creates src/libUmatBehaviour.so. You must then modify material.xml to call this new behavior law, replacing for example <Material numM="2" Lib="" Law="elasiso"> [...] </Material> by:
<Material numM="2" Lib="src/libUmatBehaviour.so" Law="umatmazars" >
<Coeff Index="1" Type="Constant" Value="1.e+10"/>
<Coeff Index="2" Type="Constant" Value="0.2"/>
<Coeff Index="3" Type="Constant" Value="0."/>
<Coeff Index="4" Type="Constant" Value="0."/>
<Coeff Index="5" Type="Constant" Value="1.15"/>
<Coeff Index="6" Type="Constant" Value="0.8"/>
<Coeff Index="7" Type="Constant" Value="1391.3"/>
<Coeff Index="8" Type="Constant" Value="10000"/>
<Coeff Index="9" Type="Constant" Value="0.7"/>
<Coeff Index="10" Type="Constant" Value="9.375e-5"/>
<IntVar Index = "1" Type = "Constant" Value = "0." />
<IntVar Index = "2" Type = "Constant" Value = "0." />
<IntVar Index = "3" Type = "Constant" Value = "0." />
</Material>You can now run the computation with the new behavior law:
apptainer exec amitex_fftp.sif mpirun amitex_fftp -nm concrete.vtk -m material.xml -c loading.xml -a algorithm.xml -s outThen visualize the results:
apptainer exec amitex_fftp.sif gnuplot < plot.gpCreate a directory containing the archive of the input files. Move into this directory, extract the archive, and modify the file permissions as follows:
tar -xzf amitex-tutorial-inputs.tar.gz # Extracts the contents of the archive.
chmod -R a+rwx $(pwd) # Grants read, write, and execute permissions to all users on the files.It is necessary to grant access permissions to other users on the files, because we will run Docker by specifying a different user.
We then enter the container with the following command:
docker run -v=$(pwd):/workdir -w=/workdir --user=1000:1000 --entrypoint=bash -it --rm gricad-registry.univ-grenoble-alpes.fr/diamond/apptainer/apptainer-singularity-projects/amitex_fftp-v=$(pwd):/workdirmounts the current directory into the/workdirdirectory inside the container.-w=/workdirsets/workdiras the working directory inside the container.--user=1000:1000specifies the user with UID1000and GID1000inside the container. This prevents commands from being executed asroot, which is safer and required to usempirun.--entrypoint=bashand-itallow an interactive Bash shell to be launched.--rmautomatically removes the container when exiting the shell.
One-line command
For users in a hurry, here is how to launch an Amitex_FFTP computation once inside the container:
mpirun -np <N> amitex_fftp <args>mpirun refuses to run as the root user, so make sure to specify --user=1000:1000 when starting Docker, or alternatively add --allow-run-as-root after each mpirun command.
Introduction
Amitex_FFTP is a massively parallel computation code built around the MPI standard, which distributes the computational workload across multiple processes. With Docker, it is only possible to use the MPI embedded inside the container. This guarantees proper operation, but limits execution to a single machine (a single node).
Running the example
mpirun amitex_fftp -nm concrete.vtk -m material.xml -c loading.xml -a algorithm.xml -s outNo parameters are passed to mpirun, so all available CPU cores will be used for the computation.
Visualizing the results
Generate the stress-strain curves using Gnuplot:
gnuplot < plot.gpThis creates concrete_stress_strain.svg, which can then be displayed using any standard image viewer.
To visualize .vtk files, you need to exit the container and use ParaView. We provide a ParaView container
here. Once the ParaView container has been downloaded, you can visualize the concrete.vtk microstructure as follows:
apptainer run paraview.sif concrete.vtk
# Then, in the graphical interface, click Apply in the Properties panel on the left
# Then, in the top menu bar, select MaterialId from the dropdown menu instead of Solid Color
# Then, in the top menu bar, select Surface from the dropdown menu instead of Outline(Advanced) User-defined material behavior law
UMAT behaviors
It is possible to define custom material behavior laws using a UMAT-compatible procedure. We will look at an example of a user-defined material behavior law used with AMITEX_FFTP. You can retrieve the example provided in the container with:
cp -r /gnu/store/$(ls /gnu/store | grep amitex_fftp)/cas_tests/comportements/polyxCC/comportement_umat .
chmod -R a+rw comportement_umatThe provided example is already compiled, so we can start by cleaning the comportement_umat directory:
cd comportement_umat
make cleanYou can now implement the desired behavior by modifying the files with your preferred text editor. Then, recompile the constitutive law with:
make
cd ..This creates comportement_umat/libUmatAmitex.so. Next, you need to modify material.xml to call this new behavior law by replacing, for example <Material numM="2" Lib="" Law="elasiso"> [...] </Material> with:
<Material numM="2" Lib="comportement_umat/libUmatAmitex.so" Law="umatBCCHPP" >
<Coeff Index="1" Type="Constant" Value="236.412E3"/>
<Coeff Index="2" Type="Constant" Value="0.35"/>
<Coeff Index="3" Type="Constant" Value="275.2E3"/>
<Coeff Index="4" Type="Constant" Value="112.4E3"/>
<Coeff Index="5" Type="Constant" Value="87.56E3"/>
<Coeff Index="6" Type="Constant" Value="363."/>
<Coeff Index="7" Type="Constant" Value="0."/>
<Coeff Index="8" Type="Constant" Value="1000."/>
<Coeff Index="9" Type="Constant" Value="10e-6"/>
<Coeff Index="10" Type="Constant" Value="1e11"/>
<Coeff Index="11" Type="Constant" Value="2.481e-7"/>
<Coeff Index="12" Type="Constant" Value="100"/>
<Coeff Index="13" Type="Constant" Value="3."/>
<Coeff Index="14" Type="Constant" Value="2.e-6"/>
<Coeff Index="15" Type="Constant" Value="0.84"/>
<Coeff Index="16" Type="Constant" Value="1e5"/>
<Coeff Index="17" Type="Constant" Value="1e5"/>
<Coeff Index="18" Type="Constant" Value="1e-6"/>
<Coeff Index="19" Type="Constant" Value="50"/>
<Coeff Index="20" Type="Constant" Value="0"/>
<Coeff Index="21" Type="Constant" Value="0.3"/>
<Coeff Index="22" Type="Constant" Value="1."/>
<Coeff Index="23" Type="Constant" Value="5.e-4"/>
<Coeff Index="24" Type="Constant" Value="50"/>
<Coeff Index="25" Type="Constant" Value="0."/>
<Coeff Index="26" Type="Constant" Value="0."/>
<Coeff Index="27" Type="Constant" Value="0."/>
<IntVar Index="1" Type="Constant" Value="0."/>
<IntVar Index="2" Type="Constant" Value="0."/>
<IntVar Index="3" Type="Constant" Value="0."/>
<IntVar Index="4" Type="Constant" Value="0."/>
<IntVar Index="5" Type="Constant" Value="0."/>
<IntVar Index="6" Type="Constant" Value="0."/>
<IntVar Index="7" Type="Constant" Value="0."/>
<IntVar Index="8" Type="Constant" Value="0."/>
<IntVar Index="9" Type="Constant" Value="0."/>
<IntVar Index="10" Type="Constant" Value="0."/>
<IntVar Index="11" Type="Constant" Value="0."/>
<IntVar Index="12" Type="Constant" Value="0."/>
<IntVar Index="13" Type="Constant" Value="0."/>
<IntVar Index="14" Type="Constant" Value="0."/>
<IntVar Index="15" Type="Constant" Value="0."/>
<IntVar Index="16" Type="Constant" Value="0."/>
<IntVar Index="17" Type="Constant" Value="0."/>
<IntVar Index="18" Type="Constant" Value="0."/>
<IntVar Index="19" Type="Constant" Value="0."/>
<IntVar Index="20" Type="Constant" Value="0."/>
<IntVar Index="21" Type="Constant" Value="0."/>
<IntVar Index="22" Type="Constant" Value="0."/>
<IntVar Index="23" Type="Constant" Value="0."/>
<IntVar Index="24" Type="Constant" Value="0."/>
<IntVar Index="25" Type="Constant" Value="0."/>
<IntVar Index="26" Type="Constant" Value="0."/>
<IntVar Index="27" Type="Constant" Value="0."/>
<IntVar Index="28" Type="Constant" Value="0."/>
<IntVar Index="29" Type="Constant" Value="0."/>
<IntVar Index="30" Type="Constant" Value="0."/>
<IntVar Index="31" Type="Constant" Value="0."/>
<IntVar Index="32" Type="Constant" Value="0."/>
<IntVar Index="33" Type="Constant" Value="0."/>
<IntVar Index="34" Type="Constant" Value="0."/>
<IntVar Index="35" Type="Constant" Value="0."/>
<IntVar Index="36" Type="Constant" Value="0."/>
<IntVar Index="37" Type="Constant" Value="0."/>
<IntVar Index="38" Type="Constant" Value="0."/>
<IntVar Index="39" Type="Constant" Value="0."/>
<IntVar Index="40" Type="Constant" Value="0."/>
<IntVar Index="41" Type="Constant" Value="0."/>
<IntVar Index="42" Type="Constant" Value="0."/>
<IntVar Index="43" Type="Constant" Value="0."/>
<IntVar Index="44" Type="Constant" Value="0."/>
<IntVar Index="45" Type="Constant" Value="0."/>
<IntVar Index="46" Type="Constant" Value="0."/>
<IntVar Index="47" Type="Constant" Value="0."/>
<IntVar Index="48" Type="Constant" Value="0."/>
<IntVar Index="49" Type="Constant" Value="0."/>
</Material>You can now run the computation with the new behavior law, after removing <Loading Tag="2"> [...] </Loading> from loading.xml, which does not work in this example:
mpirun amitex_fftp -nm concrete.vtk -m material.xml -c loading.xml -a algorithm.xml -s outMFRONT behaviors
It is also possible to define custom material behavior laws using mfront. Here we present an example of a material behavior defined with mfront, then used with AMITEX_FFTP. The first step is to generate the dynamic library containing the UMAT function:
mfront --obuild --interface=umat Mazars.mfrontThis creates src/libUmatBehaviour.so. You must then modify material.xml to call this new behavior law, replacing for example <Material numM="2" Lib="" Law="elasiso"> [...] </Material> by:
<Material numM="2" Lib="src/libUmatBehaviour.so" Law="umatmazars" >
<Coeff Index="1" Type="Constant" Value="1.e+10"/>
<Coeff Index="2" Type="Constant" Value="0.2"/>
<Coeff Index="3" Type="Constant" Value="0."/>
<Coeff Index="4" Type="Constant" Value="0."/>
<Coeff Index="5" Type="Constant" Value="1.15"/>
<Coeff Index="6" Type="Constant" Value="0.8"/>
<Coeff Index="7" Type="Constant" Value="1391.3"/>
<Coeff Index="8" Type="Constant" Value="10000"/>
<Coeff Index="9" Type="Constant" Value="0.7"/>
<Coeff Index="10" Type="Constant" Value="9.375e-5"/>
<IntVar Index = "1" Type = "Constant" Value = "0." />
<IntVar Index = "2" Type = "Constant" Value = "0." />
<IntVar Index = "3" Type = "Constant" Value = "0." />
</Material>You can now run the computation with the new behavior law:
mpirun amitex_fftp -nm concrete.vtk -m material.xml -c loading.xml -a algorithm.xml -s outThen visualize the results:
gnuplot < plot.gpSome files may be created with permissions that prevent them from being modified or deleted from outside the container. It is possible to change permissions from inside the container using for example: chmod -R a+rwx $(pwd).