Quickstart Tutorial#

Introduction#

This tutorial will explore the workflow of abaci using a simple example project.

Objectives#

In this tutorial you will learn:

How to use abaci to compile user-subroutines and run abaqus jobs
What output files abaci generates
How to provide information to abaci using a configuration file

Important

Abaci is a command-line tool - all actions are performed by entering commands into the Windows command prompt or a Linux shell terminal.

Setup#

To follow along with this tutorial you will first need to:

Install abaci
Check that Abaqus and the Intel Fortran Compiler are available at the command line
Clone or download the abaci repository (for the example project)

Get the Example Project Files#

Once you have established that Abaqus, Intel Fortran and abaci are setup correctly you can clone the abaci source repository and navigate to the example subdirectory:

  git clone https://github.com/BristolCompositesInstitute/abaci.git
  cd abaci/example

The example subdirectory contains a complete example of an abaci project including a simple implicit user subroutine (src/umat.f) and a small Abaqus input file (jobs/test-job.inp). The full file structure will look something like this:

.
|-- abaci.toml
|-- jobs
|   |-- test-job-results.pkl
|   `-- test-job.inp
|-- scripts
|   `-- post-process.py
`-- src
    |-- Abaqus_Definitions.f90
    `-- umat.f

We will use this example project for the remainder of this tutorial.

Compiling User Subroutine Code#

One of the primary roles of abaci is to compile user subroutines for use with Abaqus. Abaci interfaces with the abaqus make command to allow customising the compilation procedure.

Within the example project, you can use abaci to compile a user subroutine with the following command:

  abaci compile

You will notice that a new folder has been created in the example directory called scratch. This is the output folder and is where abaci places all generated files during execution. If we look within this folder we will see a number of files and directories:

scratch
|-- abaci-0.log
`-- lib/
    |...

Two particular items of importance in the output folder are:

abaci-xx.log file: Log files that are created everytime abaci is run to store useful detail about the run
lib/ folder: contains the user subroutine source files and compiled library files

Hint

To see more information about what abaci is doing ‘behind the scenes’, you can run any command with the --verbose flag, e.g. $ abaci compile --verbose

Running an Abaqus Job#

The run subcommand will do everything that the compile subcommand does but it will also run one or more abaqus jobs after compilation.

Within the example project, you can run an Abaqus job with the following command:

  abaci run test-job

This time, the command will take longer to run and will output more information.

You will also notice that another subfolder called test-job_0 has been created in the scratch output folder. This is the job folder and contains everything required to run an Abaqus job, including the previously-compiled user subroutines.

Hint

Abaci will create a new job folder every time you launch a job by incrementing the numbered suffix.

In this example, test-job is the name of the job we wish to run. We can also specify other job names or job tags to run a group of jobs. We can view a list of possible jobs and their tags with the show subcommand:

  abaci show jobs
test-job default,test

In this example project, there is only one job called test-job and it has the tags default and test. We could therefore also run this job with:

  abaci run test

Running a Job in Debug Mode#

To help identify or diagnose bugs in your user subroutine code, you can compile and run your code in ‘debug’ mode by adding the --debug flag:

  abaci run test --debug

Debug mode will add a number of additional compiler flags to check for common errors. Most notably, debug mode enables runtime checks, which adds extra code to your compiled user subroutine to check for the following error conditions:

Out-of-bounds array access
Use of uninitialised variables in expressions
Use of unallocated arrays or uninitialised pointers
Checking of subroutine and function interfaces

Recommendation

Regularly check that your code runs successfully in debug mode, to ensure that subtle bugs are not hidden in your code.

The Configuration File#

You have now seen how to run abaci from the command line using the example repository, but how does abaci know about your code files and abaqus .inp job files? This information is stored in the abaci.toml configuration file.

When abaci starts, it will look for a configuration file called abaci.toml in the current directory.

If you open the abaci.toml file in any code editor, you can see information about the example project including:

The name of the project
The name of the output folder
Path to the Fortran user-subroutine source file
Information about the test-job

Other information that can go in the configuration file includes:

Extra command line flags to pass to Abaqus or the compiler
Information about auxiliary source files, including C/C++ sources
Information for specifying regression checks and post-processing commands
Settings for controlling job submission to SLURM
Details for using code from remote repositories as dependencies

Next Steps#

Now that you have completed the quickstart tutorial, take a look at the How-to Guides for how to perform common tasks with Abaci.

Detailed documentation can be found in the Command Line Interface Reference and the Configuration File Reference.