Chapter 2. Getting Started with Anura3D
Authors: Alba Yerro, Alexander Rohe, James Fern, Francesca Ceccato, Luis E. Zambrano-Cruzatty
Anura3D is a software tool for numerical analysis of geotechnical problems developed by the Anura3D MPM Research Community and distributed as open-source code programmed using Fortran. This software is a 2D/3D implementation of the material point method (MPM) and it is used for simulating the physics involved in soil-water-structure interaction and large deformation problems. There is no warranty or liability in any sense for the use of the provided software or results. The license is available here. The list of implemented and under development features is provided in Table 1.1.
This chapter explains how to get started with Anura3D. The basis to perform a numerical simulation is provided in Section 2.1. Instructions for downloading Anura3D are given in Section 2.2. Then, the process to compile the code is explained in Section 2.3. Subsequently, the installation instructions for both pre- and post-processing software are presented in Sections 2.4 and 2.5. In both cases, the use of third-party software is required.
The process to perform a numerical simulation consists of three parts as follows.
- Creating input data with the pre-processor (e.g., GiD software)
- Performing calculation with the Anura3D software (compiled executable)
- Visualisation of results with the post-processor (e.g., ParaView software)
In this tutorial manual, we will use GiD as the pre-processor and ParaView as the postprocessor, though other pre- and post-processors may be used (the interface between Anura3D and the pre- and post-processing software is completely open). A schematic description of the calculation procedure is presented in Figure 2.1, and each step is explained below in this chapter.
Figure 2.1: List of features available in Anura3D 2023
Anura3D requires two input files – the GOM file and the CPS file. Both files can be generated with the GiD pre-processing software (the installation instructions of GiD are given in Section 2.4). Both files are text files (ASCII), which can be modified manually by opening them in a text editor and changing the text. This is typically done for parametric analyses for which the value of a specific parameter is changed. Users could eventually create their own GOM and CPS files with alternative pre-processors (different than GiD) if desired.
Definition of problem: GOM file
The GOM file describes the geometry of the problem, the material data sets, initial and boundary conditions, loading conditions, excavation phases, contact properties, number of material points, and computational mesh. When a model is created, GiD writes this information into the GOM file.
Definition of calculation data: CPS file
The CPS file describes the calculation data such as the computation method, calculation time step data, gravity data, load multipliers, quasi-static convergence, damping, strain smoothing,output data, etc. Unlike the GOM file, a CPS file is required for each calculations phase. GiD is used to define the initial CPS file required to initiate the calculation (i.e., CPS_001 file), whilst the subsequent CPS files are generated at the end of each calculation phase. Additionally, Anura3D utilizes the UMAT format
Anura3D is a stand-alone programme which can be executed from the Windows command line or by running the calculate.bat file in the project folder projectname.A3D. The process to download and compile the code is explained in Sections 2.2 and 2.3.
Anura3D creates results by writing several output files (Figure 2.1). These files have to be treated differently depending on the file type.
VTK files
Anura3D stores most of the output information in a set of files with VTK extension. The ParaView post-processing software is recommended to visualise the results stored in those output files (the installation instructions of GiD are given in Section 2.5). There are four different types of VTK files depending on the type of data stored in them, and are as follows.
- projectname_MeshData_SSSTTTTTT.VTK
- projectname_MPScalar_SSSTTTTTT.VTK
- projectname_MPVector_SSSTTTTTT.VTK
- projectname_MPTensor_SSSTTTTTT.VTK
where projectname is the user-defined name of the project and SSS and TTTTTT are the automatically assigned calculation step and time step numbers, respectively. The variables of the VTK files are listed in Figure 2.2.
Figure 2.2: Scalar, vector and tensor components in the VTK files.
The mesh data, such as the mesh location and active elements, is stored in MeshData. The material point data is stored in:
- MPScalar: collects all scalar quantities such as material point number, pore water pressure, mean and deviatoric stress, etc.
- MPVector: collects all vector quantities such as velocity, displacement, etc. The components of the vector are (X,Y,Z) in global coordinate system. For 2D analysis the third component (Z) is zero.
- MPTensor: collects tensorial quantities such as stress and strain. The tensor has 9 components, that ParaView enumerate from 0 to 8 starting from the top left corner of the matrix, as indicated in Figure 2.3.
Figure 2.3: Components of the stress tensor in 2D and 3D in Paraview.
Other output files
Any text editor or spreadsheet software can be used to visualise the other output files such as the *.PAR and *.ENG files. The PAR file stores data from a given material point, which has to be specified in the CPS file, $$OUTPUT_MATERIAL_POINTS. The ENG files gives the values of kinetic energy, internal work of the system, and time step information. Chapter 3.5 explains how to create and read text output files.
The Anura3D source code is stored in the Anura3D GitHub repository in the src folder. You can visualize the files by clicking on each file in the src folder. You can download all the files by clicking on "Code" and then select "Download ZIP". We recommend that external users and developers fork the code. Information on how to fork a repository in GitHub can be found here.
Before performing any simulation with Anura3D, you must compile the code and create an executable file.
Anura3D is written in Fortran language and requires a text editor and a compiler to visualize the code and create the executable. The current version (Anura3D 2023) is supported only on Windows operating systems and requires Visual Studio (VS) and a Fortran Compiler, distributed in the oneAPI package (Base + HPC Toolkits). Since VS is a dependency for the oneAPI software, not all combinations of VS and oneAPI are compatible. Check the compatibility requirements using this link. Make sure to include the Intel oneAPI Math Kernel Library (oneMKL) during the installation of the Intel oneAPI Base Toolkit.
The VS Community version 2022 is recommended and is freely distributed. The VS Community version 2019 is also compatible. Similarly, the oneAPI is suggested. Intel offers academic licenses, provided an active .edu email address.
The following steps are recommended for the successful installation of VS and oneAPI.
- Check that the minimum hardware requirements for VS and oneAPI are fulfilled.
- Download and install VS first.
- When installing VS, the user is prompt to select custom workloads. Select "Desktop development with C++" as shown in Figure 2.4.
- For different versions of VS the corresponding C++ components must be installed. Consult this site's information to get help.
- Continue with the installation process following the instructions provided in the VS installer.
- Download and execute the installation file for the oneAPI (base and high performance computing toolkit). Check that oneAPI is compatible with the previously installed VS version.
- Depending on the oneAPI version, the installation manager will indicate if VS was installed successfully. If that is not the case, instructions are provided by the oneAPI installation manager.
- In the case that VS was installed successfully, proceed to install oneAPI following the instructions on the screen.
- Once the installation is completed, open a new project in VS as shown in Figure 2.5.
- If Fortran appears under the All languages drop-down list as it is shown in Figure 2.6, the installation of VS and oneAPI is successful, and they are integrated correctly.
Figure 2.4: Visual Studio installer - Workload tab.
Figure 2.5: Visual Studio 2022: Creating a new project.
Figure 2.6: If Visual Studio 2022 and oneAPI are integrated correctly, Fortran should be available in the dropdown menu.
Once the installation of VS and oneAPI is completed, the Anura3D code can be compiled. The following steps show how to build the code together with the included constitutive models.
- Navigate the code folder to the ".../Anura3D/VS" folder.
- Find and double click on the Anura3D.sln file.
- VS should initialize. If the screen observed in Figure 2.7 doesn’t automatically appear, open the Anura3D.for file from the Solution Explorer window. Select "Release" from the solution configurations dropdown menu.
- Click on the Build menu (Figure 2.7).
- Click on Build Solution (Figure 2.8). This will compile the Anura3D executable together with the constitutive models (DLL files).
- If the compilation is completed successfully, the executable is stored in the ".../Anura3D/VS/Release" folder.
- The constitutive models’ DLL files can be found in the ".../Anura3D/VS/Release/SoilModels" folder.
- For troubleshooting look at the error messages shown in the Error List (select View/Error List from the top menu) or the Output window as it is shown in Figure 2.9 and direct your questions to the forum at www.Anura3D.com specifying your VS and oneAPI versions with the error message displayed a the Error List or Output window.
Figure 2.7: Anura3D code in Visual Basic 2022.
Figure 2.8: The code will be compiled after clicking on Build Solution.
Figure 2.9: Error List window in Visual Studio Community 2022.
GiD is a licensed software with free one-month license for first-time user, and can be renewed for free up to three times. The installation process is as follows.
- Download the installation files (i.e. v16) at https://www.gidsimulation.com/gid-for-science/downloads/
- Check the version number and operating system, and click on the "Download" button as shown in Figure 2.10.
- Start the installation and follow the on-screen instructions.
- Obtain the one-month free license at: http://www.gidhome.com/purchase/passwords
- Select the version number, license type, and time period as shown in Figure 2.11.
- Follow the instructions on the website and provide the required information. A one-month free password will directly be provided (at the bottom of the website).
- Enter the password in the "Enter password window" in GiD as shown in Figure 2.12, or navigate to Help/Register GiD/Local/Enter Password in the menu.
The Anura3D 2023 problemtype is meant to be used with GiD v16.0. GiD community and Anura3D MPM Research Community do not support the use of different versions.
Figure 2.10: Download GiD v16 installation files.
Figure 2.11: Obtain one-month free password for GiD.
Figure 2.12: Enter password in GiD.
The Anura3D 2023 "problemtype" folder is needed to use the Anura3D Software features in the GID pre-processor (more in section 2.1). The folder is partially pre-assembled and distributed with the Anura3D code. The "problemtype" folder must have the structure shown in Figure 2.13 to be completely functional, which includes the executable and other dependencies.
Figure 2.13: "Problemtype" folder structure. The green files represent the path where the Anura3D_2023.exe and the constitutive models *.DLL files must be pasted.
To complete the assembling of the problemtype file and ensure its functionality proceed with the following steps:
- Copy the executable file from ".../Anura3D/VS/Release/" to "...Anura3D_2023.gid/exec/".
- Copy the DLL files in "...Anura3D_2023.gid/DLL/" to "...Anura3D_2023.gid/dll/".
- Finally, copy the Anura3D 2023 "problemtype" into the GiD installation directory as show in Figure 2.14.
Figure 2.14: Copy Anura3D 2023 problemtype into GiD installation directory.
ParaView is an open-source software under a permissive BSD license and is, thus, free to use with Anura3D. The original ParaView software will be used without any modifications of its source code. The following steps have to be performed to install ParaView.
- Download the installation files of the latest supported ParaView version (i.e. v5.11) at: http://www.paraview.org/download
- Select the version number, download type and operating system, and click on the button as shown in Figure 2.15.
- Start the installation executable and follow the on-screen installation instructions.
Figure 2.15: Download ParaView v5.11 installation files.
After installation ParaView is ready for use to post-process Anura3D calculation results.
Important note for the first time use of ParaView If you use ParaView for the first time after installation, the following changes are recommended to secure an improved visualisation of the results.
- In the ParaView main menu, choose <Settings...> as indicated in Figure 2.16 and the "Settings" dialogue box will open.
- Select the tab "Color Palette" as indicated in Figure 2.17
- Click on drop down menu and select the option as shown in Figure 2.17.
- The colours should be updated. Click on to save the changes.
- Choose from the menu and select the options of the drop down menu as indicated in Figure 2.18.
These are one-time actions and the choices will be stored as default for any further use of ParaView.
Figure 2.16: Change settings in ParaView.
Figure 2.17: Change of "Color Palette" in ParaView.
Figure 2.18: Select "View" options in ParaView.