====== Abaqus ======
Abaqus is a commercial finite element package. Nguyen lab shares Abaqus license with other WSE faculties via MARCC. Abaqus/ Standard is an implicit finite element solver while Abaqus/ Explicit uses explicit algorithms for nonlinear finite element problems. Abaqus/ Standard allows Fortran-based (C++ support is also available) user-defined material (UMAT), and user-defined element (UEL) subroutines to develop new constitutive models and elements in Abaqus/ Standard. Abaqus/ Explicit counterparts are known as VUMAT and VUEL. While these are popular user-defined features in Abaqus, it also offers a few more features to be programmed by the user.
Abaqus is officially supported on Windows and Red Hat Linux (and CentOS). Although the installation script can be hacked to get Abaqus installed on Ubuntu and other desktop distros of Linux, previous experience wasn't great with it. It often lacks multiple features. Installing on Windows is highly suggested for Abaqus.
Abaqus CAE is a pre- and post-processing package bundled with Abaqus solver. It allows the creation of CAD models, meshing, defining boundary conditions, and loading via GUI. But you might want to learn to create Abaqus input files if you're using user-defined features. To use Abaqus's user-defined features, you will need the Intel Fortran (and C++) compiler installed with Microsoft Visual Studio. Abaqus output is written in .odb file format and you will need Abaqus CAE (or Viewer) to view and process those results.
==== Abaqus documentation (https://help.3ds.com) ====
Abaqus documentation is available at https://help.3ds.com. You will need to open an account to access the documentation. Once you login, you can search for specific version of Abaqus and navigate to the documentation.
Abaqus installation also comes with a **.exe** file for Abaqus documentation which will you redirect you to the above website. You can find older version of documentation publicly hosted online by different institutes. But we recommend using the documentation from the installed or latest version.
==== Abaqus Licensing ====
Unlike Tahoe and FEniCSx, Abaqus is a commercial finite element software. Johns Hopkins has 350 Abaqus licensing tokens for Abaqus/Standard, Abaqus/Explicit, and other SIMULIA products. Running a simulation on a single CPU on Abaqus/Standard or Explicit takes up 5 licensing tokens and it increases with the number of CPUs being used (see below).
{{:abaqus_token.png?900}}
There exists a computational bottleneck; your simulations will not run any faster if you keep using more and more CPUs beyond a limit. So find that limit and use the resources carefully. **It is very important to ensure not to reserve all or most of the licenses available campus-wide as a single user.** Please be considerate of others and if you notice any user is taking advantage of the licensing system, please let the system administrator at the Rockfish know about it. Similarly, for Abaqus/CAE try using more Viewports to open multiple ODB files in a single instance rather than opening multiple instances of it.
==== Installing Abaqus on Windows ====
ABAQUS is not forward compatible means ABAQUS 2021 won't be able to open the .CAE and .ODB files generated by ABAQUS 2022 or later versions. But the newer version can open files from an older version. So decide on an appropriate version that you can use for a long time (check what version Rockfish offers as well in case you have to run simulations there and transfer your files to local computer). You can download the software from [[https://software.wse.jhu.edu/]] and install it by yourself by obtaining the license information from WSE IT (or ask one of your labmates who uses ABAQUS for licensing information). Please make sure to select ABAQUS/Standard and Abaqus/Explicit solver with CAE package and CAA API components during installation.
**Make sure to obtain the research license for Abaqus from WSE IT. Academic license have limited functionalities.**
==== Installing Microsoft Visual Studio and Intel oneAPI ====
**Visual Studio and Intel oneAPI have to be installed in that order while Abaqus can be installed at any time.**
To be able to leverage user-defined features of Abaqus, **Microsoft Visual Studio** and **Intel Fortran Compiler** are required to be installed. Intel Fortran (and C++) compiler is a part of Intel oneAPI Toolkit which is available for free. Download the latest stable version of Intel oneAPI, both Base Toolkit and HPC Toolkit. The Base Toolkit has the compiler and oneMKL package and HPC Toolkit has the parallel computing packages. Please make sure to check which version of Microsoft Visual Studio is compatible with that particular version of Intel oneAPI. Download the compatible version of the community edition of Visual Studio. Both these software are freely available.
- Start the installation procedure with Visual Studio. Make sure to select ''Desktop development with C++'' on the installation page while other settings could be default. The installation process is trivial. \\ \\
- Then install the Intel oneAPI Base Toolkit and Intel oneAPI HPC Toolkit, respectively. Default installation should work and both of these software will recognize existing Visual Studio and link itself. \\ \\
- Upon successful installation, Intel oneAPI packages will be installed in C:\Program Files (x86)\Intel\oneAPI directory on Windows. Navigate further into the directory and check the folder ''C:\Program Files (x86)\Intel\oneAPI\compiler\2021.1.1\windows\bin\intel64'' (version could be different) for the ''ifort'' executable. Copy the path to a text editor for later use. \\ \\
- Now navigate to the ''C:\Program Files (x86)\Intel\oneAPI\compiler\2021.1.1\env'' directory (again, the version could be different) and locate the ''vars.bat'' file. If your directory names are arranged differently for Intel oneAPI, you can search for the ''vars.bat'' through Windows Explorer and locate the one under the compiler directory. There will be other ''vars.bat'' files for different oneAPI packages, so, please make sure you find the right one. Copy the path to a text editor for later use. \\ \\
- Now please locate the ''abqXXXX.bat'' file (XXXX for version) in ''C:\SIMULIA\Commands''. Open the ''abqXXXX.bat'' file with a text editor. You will need to save the file later as an administrator. To do so, open Notepad from the program menu, run it as an administrator, and then open the file or use the Notepad++ text editor to open the file. \\
SET PATH=%PATH%;C:\Program Files (x86)\Intel\oneAPI\compiler\2021.1.1\windows\bin\intel64;
call “C:\Program Files (x86)\Intel\oneAPI\compiler\2021.1.1\env\vars.bat” intel64
The first line here is the path directory for the ''ifort'' compiler and the second line calls the batch file (or script) to initialize the environment variable for the ''ifort'' compiler when the ABAQUS command is invoked. \\ \\
- Now, open either Abaqus Commands, cmd, or Powershell from the Windows start menu and type the following to check and verify the installation. This should return all the system information, including the linker and compiler on the terminal.
abaqus info=system
- The following commands can be used to verify installation and linking as well. For **successful** installation and linking, it will show PASS on the terminal.
abaqus verify -user_std #Abaqus/Standard user subroutine feature
abaqus verify -user_exp #Abaqus/Explicit user subroutine feature
abaqus verify -all #All Abaqus feature (this will take time)
==== Linking Intel oneMKL to ABAQUS (optional) ====
Intel oneMKL (Math Kernel Library) is also part of the Intel oneAPI distribution. Intel oneMKL has Intel's implementation of BLAS, LAPACK, FFTW, and other math libraries which can be used in the user subroutine feature of ABAQUS. Learn a little bit about these libraries.
- Navigate back to ''C:\SIMULIA\Commands'' directory, and open the ''abqXXX.bat'' file again. Add the following line below the previously added lines for the ifort compiler. This will initialize the environment variables for oneMKL when ABAQUS is called. call "C:\Program Files (x86)\Intel\oneAPI\mkl\2021.1.1\env\vars.bat" intel64
- Now navigate to ''C:\SIMULIA\EstProducts\2020\win_b64\SMA\site'' (or similar directory) based on your ABAQUS installation and locate ''win86_64.env'' file and open it as an administrator (same as before). Find the following line and add ''/Qmkl:sequential'' in between other compiler flag options. The file should now look as below for that line.
compile_fortran=['ifort','/Qmkl:sequential', ... ...
You should be able to use the Intel oneMKL library now with ABAQUS. Apparently, by using ''/Qmkl:parallel'', you may be able to use the parallel version of oneMKL, however, it has never been tested we do not think is is necessary either for the ABAQUS user subroutine feature so far.
==== Programming Abaqus user subroutines ====
User-defined subroutines available via Abaqus/Standard and Abaqus/Explicit allows the users to include new constitutive model for materials, new element technologies, novel multiphysics coupling, and extend the built-in features. While Abaqus allows programming user subroutines in C, C++, and Fortran. However, because of the legacy reason, it is more popular to write Abaqus subroutines in Fortran instead of C and C++. Before you start programming Abaqus user subroutine, make yourself familiar with the fundamentals of the programming language of your choice (Fortran or C/C++).
Don't underestimate the power of Fortran for being a old language. It's still one of the fastest programming language for numerical computing. Under the hood, MATLAB and NumPy uses Fortran libraries. Learn about [[https://en.wikipedia.org/wiki/Fortran| Fortran history]] to understand F77 coding styles and how they are different now (comparison between F77 vs. F90). For legacy reasons, subroutine templates provided by Abaqus/Standard follow F77 standard (Abaqus/Explicit templates are different). We recommend coding the subroutine in a fixed form (save the Fortran files with ''.for'' extensions) but you are not limited by F77 features. As long as the compiler supports you can use features from latest Fortran version in your Abaqus subroutine.
* [[https://fortran-lang.org/learn/ | Learning resources on fortran-lang.org ]].
* [[http://annefou.github.io/Fortran/ | Modern Fortran materials by Anne Fou ]]
* [[https://masuday.github.io/fortran_tutorial/| Modern Fortran Tutorial by Yutaka Masuda ]]
* [[https://www.fortran90.org | Fortran 90 website ]]
* [[https://fortranwiki.org/fortran/show/HomePage | Fortran Wiki webpage ]]
* [[https://fortran-lang.org/learn/rosetta_stone/| Fortran for Python programmers]]
* [[https://stevelionel.com/drfortran/allposts/ | Blog posts from Doctor Fortran ]]
* [[https://bristolcompositesinstitute.github.io/RSE-Guide/abaqus-user-subroutines/index.html| Best practices for Abaqus user subroutine by Bristol Composite Institute ]]
A list of user subroutines available from Abaqus can be found here: https://docs.software.vt.edu/abaqusv2022/English/SIMACAESUBRefMap/simasub-c-gen-idxusubroutinelist.htm. For most updated list, you should check Abaqus documentation from Dassault Systemes website at https://help.3ds.com (you will need to create an user account login). Among those user subroutines, user material subroutine (UMAT) and user defined element (UEL) in Abaqus/Standard are readily used in academic research to implement new constitutive model and new element technology, respectively. VUMAT and VUEL are Abaqus/Explicit counterparts of the You should read the documentation very thoroughly and understand how these subroutines work before start working on them. Please remember, Abaqus can recognize one Fortran file at the time of execution. If you would like to use multiple user subroutines, you will have to put them in a single Fortran file or arrange it in a way that your main Fortran file can have call other files.
* **UMAT:** If you can express your constitutive model and spatial tangent in terms of Cauchy stress, you perhaps need a UMAT. In this case you can take advantage of the element formulation available via Abaqus such as hybrid element, incompatible model element, elements with hourglass stabilization, etc. UMAT subroutines are called at each integration point and the subroutine needs to return (at least) the stress and spatial tangent of the material which are later used to form the tangent (stiffness) matrix and residual vector.
* For incompressible hyperelastic material, use **UHYPER** subroutine. \\ \\
* **UEL:** If you need a total Lagrangian element formulation, or you need a different element technology beyond what Abaqus offers such as F-bar or B-bar type element to alleviate volumetric locking of incompressible or nearly-incompressible materials or if you want to analyze multifield models which are not available in Abaqus such as chemo-mechanical model for hydrogels or phase-field model for fracture, you will need to program a UEL subroutine. When programming UEL subroutine, you will have to program the constitutive response as well, i.e., a UMAT-like behavior also needed to be programmed.
* In case you want to use built-in material models provided by Abaqus with your own element formulation, consider using **UELMAT**.
Both UEL and UMAT requires substantial amount of programming by the user and needless to say lots of debugging as well. For UEL subroutine, pre- and post-processing are also tricky using Abaqus/CAE and Abaqus/Viewer. So, our lab created some template code-base and tutorial for Abaqus/Standard user element subroutine (UEL) implementation which are available in the following GitHub repositories:
* Abaqus UEL for isotropic linear elasticiity on GitHub: [[https://github.com/NguyenLabJHU/Abaqus-UEL-Elasticity]]
* Abaqus UEL for hyperelasticity on GitHub: [[https://github.com/NguyenLabJHU/Abaqus-UEL-Hyperelasticity]]
Documentation for these repositories are available at this [[https://livejohnshopkins-my.sharepoint.com/:f:/r/personal/tnguy108_jh_edu/Documents/Nguyen%20Lab/Abaqus%20Tutorials?csf=1&web=1&e=IzeXD7 | OneDrive folder of our lab]] (you will need access granted by Vicky).
=== Additional resources ===
- [[https://github.com/nasa/CompDam_DGD/| Comp-DGD by NASA ]]:: This is an Abaqus/Explicit VUMAT project by NASA. While it may not be related to our research, but the follows good software practices.
- [[https://github.com/HenannResearchGroup?tab=repositories| GitHub repository from Henann Research group at Brown ]]: A collection of different types of Abaqus subroutines by David Henann's group at Brown.
- Notes on [[https://imechanica.org/files/Writing%20User%20Subroutines%20with%20ABAQUS_0.pdf| Abaqus user subroutine on iMechanica]]: This document is based on a very old version of Abaqus. You should consult the Abaqus manual for additional subroutine-related documentation.
- Prof. Allan F. Bower's class on [[https://www.brown.edu/Departments/Engineering/Courses/En2340/| Computational Methods in Solid Mechanics at Brown University]]: This class covers different finite element formulation (mechanical to multiphysics) and their implementation in a custom Fortran based FEA code which shares the same user subroutine format as Abaqus.
- Prof. Allan F. Bower's [[https://github.com/albower/EN234_FEA| FEA Code on GitHub]]. This is an extended version of the FEACHEAP code (http://solidmechanics.org/FEA.php) which supports Abaqus-style user subroutine programming. This code can give you an idea of the orgranization and programming style as well, but be careful about the bugs if you use the code (there is no license available for this code on GitHub so we do not recommend using it).
==== Executing Abaqus User Subroutine ====
Open Abaqus Commands, cmd, or Powershell, and use the following command to run Abaqus analysis.
abaqus interactive analysis double ask_delete=off job=job_name input=input_file.inp user=user_subroutine.for cpus=no_of_processors
interactive processes run sequentially, double is machine precision, and ask_delete=off will delete and overwrite the old job with the same name without asking (if that's what you want). You can create a PowerShell script on Windows or a bash script on Linux to run the job efficiently and/or even run multiple jobs at the same time.
Open job_name.dat and job_name.msg file in any text editor to see the details of the simulation. To check the convergence log during simulation, open a new pane or tab on the terminal and write:
==== Running Abaqus on Rockfish (and previously MARCC) ====
As of 2023, Rockfish has replaced MARCC as JHU's HPC. Verify the lines in the header to make sure your email, HPC partition, runtime, etc. are configured correctly. Additionally, make sure the correct Abaqus module is loaded for your use case.
[[https://github.com/NguyenLabJHU/Rockfish-HPC-Scripts| This GitHub repository]] contains batch scripts to run Abaqus on Rockfish and MARCC (this is a private GitHub repository, and you will have to have an account added to the Nguyen Lab account to access this.). Scripts for Rockfish and MARCC are almost identical, and you can create your own from these if you need to.