Developer Notes#

This page contains useful under-the-hood information about abaci for new contributors and developers

Implementation Language#

Abaci is implemented in Python and designed to be run using an existing Abaqus Python installation:

  • To avoid needing to install or redistribute Python for Abaci

  • To allow using Abaqus Python libraries for reading ODB files

Abaqus Python is 2.7, hence Abaci is implemented using Python 2.7

It is also for this reason, that any Python dependencies that Abaci uses are bundled and redistributed (under their respective licenses) with Abaci.

Repository Structure#

  • .github/workflows: GitHub actions (CI) workflow files

    • DeployDocs.yml: builds this documentation site (using Sphinx) and deploy to GitHub pages

    • MakeInstaller.yml: builds installers for Windows and Linux and attach to new GitHub releases

  • docs/: all source files for this documentation site (written in Markdown using Sphinx)

  • example/: a self-contained example project for using abaci

  • media/: icon files and images used for documentation

  • scripts/: abaci launch scripts and installer files

    • abaci: abaci launch script for Linux

    • abaci-installer.nsi: script file to generate the Windows installer using the Nullsoft Scriptable Install System

    • abaci.cmd: abaci launch script for Windows

    • install: Linux installer shell script

    • install-windows: alternative command line install script for Windows

  • src/: main abaci source files

    • abaci/: Python source code for Abaci program

    • fortran/: Fortran code for generating tests

    • redist/: redistributed (bundled) library dependencies for Abaci

    • abaci_main.py: main Python entry point for Abaci program

  • test: unit testsuites for abaci

Creating a new release#

  1. Update the version number in src/abaci/cli.py (line 23)

  2. Update the version number in README.md

  3. Update the CHANGELOG.md file with new release version and changes summary

  4. Create a new release on GitHub with tag set to the new version number (prefixed with v)

    • This will trigger a GitHub actions workflow to generate the Windows and Linux installer files, and attach them to the new release

Contents of a job folder#

When a job is run, a new job folder is created in the output directory (default scratch/). All the output files from Abaqus will be placed in this folder. This section explains other files generated by abaci that are found in this folder.

  • lib/: A copy of the user subroutine source files and assocaited compiled objects. This is copied to the job folder to ensure that there is always a record of which user subroutine code generated which job results.

  • abaci-cache.pkl: A Python Pickle file used by abaci to store information about the abaqus job. It is used by abaci to allow rerunning post-processing commands on a completed job (using the abaci post subcommand).

  • abaqus.stdout: Output generated by Abaqus when the job was run. You can also view this by adding the -s option when running abaci.

  • abaqus_v6.env: This configuration file is read by abaqus to configure the analysis. It is generated by abaci to point abaqus towards the pre-compiled user subroutines in the lib folder.

Contents of the lib folder#

The <outputdir>/lib folder contains various files associated with the compiled source files. This section explains some of the types of file found in this folder.

  • mod/: Contains Fortran module files. These are like automatically generated C header files; they are used to check interface definitions where procedures are called. They are needed here when compiling unit tests, so we can check the interface of any subroutines you call from the main user subroutine code

  • abaqus_v6.env: This configuration file is read by abaqus make to configure the compilation procedure. It is generated by abaci to augment the default compiler flags with extra ones for various checks

  • abaqus-make.stdout: contains the compiler output generated when running abaqus make. You can also view this by adding the -s option when running abaci.

  • optrpt: a compiler optimisation report generated by the compiler. This tells you which parts of the user subroutine code were vectorized, inlined etc. It will be empty if abaci is run in debug mode, since optimisations will be disabled.

  • standardU.dll/libstandardU.so/explicitU.dll/libexplicitU.so: The shared object library file containing all the compiled user subroutine code. It is this file that is loaded by abaqus when it looks for precompiled user subroutines.

  • .o/.obj: Intermediate compiled object files generated when compiling auxilliary C/C++ sources or Fortran unit tests.

  • test-driver.f90: Source code for the program that executes the test suites. This is generated by abaci.

  • tests.log.stdout: Output generated by the last execution of the test driver (abaci test).

In the output folder (parent folder to lib), you will also find digest.pkl: This file caches a hash of the source files. It is used to determine if abaci can skip compilation because the source files haven’t changed.