Introduction

Description

FEPX is a finite element software package for polycrystal plasticity. It is well-suited to model the global and local mechanical behavior of large polycrystalline solids as aggregates of grains as well as associated microstructural evolution through a highly scalable parallel framework. Each grain is discretized by finite elements which have a crystal behavior. This includes:

  • Nonlinear kinematics capable of resolving large (or finite) strains and large rotations,

  • Anisotropic elasticity based on crystal symmetry,

  • Anisotropic plasticity based on rate-dependent slip restricted to dominant slip systems,

  • Appropriate state variable evolution for crystal lattice orientation and slip system strengths.

FEPX strives to be a user-friendly, efficient, and robust tool. All of the input data are prescribed non-interactively, using ASCII files. FEPX works hand in hand with Neper, which can be used for both generating the input polycrystal mesh and post-processing the simulation results. As a finite element code, FEPX allows for complex loadings on general domains, but it also offers capabilities specific to RVE-type calculations (uniform loading of cubic polycrystals).

Resources and Support

Several complementary resources describing FEPX are available:

Resources for Neper can be accessed from https://neper.info.

Installing FEPX

FEPX is written in Fortran, and it can run on any Unix-like system (including MacOS). Parallelization of the code is achieved via OpenMPI. Compilation is performed via CMake:

  • Create a build directory, for instance as a subdirectory of FEPX’s src directory:

    $ cd src
$ mkdir build

  • Run CMake from within the build directory, pointing to FEPX’s src directory:

    $ cd build
$ cmake ..

  • Build FEPX:

    $ make

    This generates the fepx binary file. To make it available system-wide, run (as root):

    $ make install

This procedure uses the default configuration options and should work out-of-the-box if you have a Fortran compiler, OpenMPI, and CMake installed. Testing is performed on GFortran version 6 and greater, and OpenMPI version 2 and greater (other Fortran compilers and MPI distributions may also work, though they are not explicitly supported or tested). A minimum version of CMake version 3.0 is required to utilize the build system.

Fine Configuration

Program configuration options can be specified, before installation, using CMake variables. This can be done using a terminal tool:

$ ccmake ..

or an interactive tool:

$ cmake-gui ..

or directly at the command line, using Cmake’s -D option:

$ cmake -D<VARIABLE1>=<VALUE1> -D<VARIABLE2>=<VALUE2> ..

The program configuration variable concerns the precision of the output:

  • OUTPUT_PRECISION, default 1e-12 (12 decimal digits).

    Values are printed to this precision, and smaller values (in absolute value) are printed as 0.

Testing FEPX

FEPX comes packaged with tests and reference outputs. To run the tests, execute the following from your build folder:

$ make test

or (equivalently):

$ ctest

This runs the tests in Normal mode, for which the produced output files are compared to reference ones.

The (packaged) reference output files are generated on Ubuntu version 22.04, using compiler GFortran version 11.4.0 and OpenMPI version 4.1.2 (note: CMake will switch to the MPI Fortran compiler to build FEPX, which will be built against GFortran version 11.4.0). It is expected that different versions may result in minor (insignificant) changes to the output, though this will generally result in failed tests. If this happens, you may switch to the Minimal mode as described in the following. The testing mode is controlled by variable BUILD_TESTING_MODE, which may be changed as described in fine_configuration.

  • The (default) Normal mode checks if the program completes without error and if the produced output is the same as a set of reference output.

  • The Minimal mode only checks if the program completes without error. This mode may be useful when installing on a machine which has program or library versions different from the ones with which the reference output was generated.

  • The Writing mode overwrites the reference outputs with the generated output. This mode may be useful when installing on a machine which has program or library versions different from the ones with which the reference output was generated and the user needs a reference output before making changes to the source code.

In the standard case where the testing mode is Normal, it is further possible to choose how the produced output is compared to the reference output using the variable BUILD_TESTING_DIFF, which can take the value of Soft to allow for small differences (the default, recommended) or Hard otherwise.

Note

As the program is tested on a different environment from the one on which the reference files were generated (specified above), it may happen that some tests fail. This problem can generally be ignored.

Getting Started

Running a simulation requires two files: a Mesh File (simulation.msh), which describes the material, and a configuration file, which defines the simulation itselt, as described in Configuration File (simulation.cfg) and related sections. With these files at disposal, to run a serial simulation on a local computer, the fepx binary must be run in a terminal (from the directory where the input files are located):

$ fepx

For parallel simulations, FEPX must be run as:

$ mpirun -np <N> fepx

where <N> refers to the number of MPI processes (typically equal to or less than the number of cores on the local machine).

To perform simulations across multiple computational nodes on an HPC cluster, a submission script that conforms to the specific job scheduling program is necessary (see examples in Submitting FEPX to a Job Scheduling Program).

During a simulation run, FEPX returns real-time messages in the terminal and, upon successful completion, prints requested output data in a Simulation Directory (.sim) named simulation.sim. The .sim format is a human-friendly database format which is shared with (and readable by) Neper.

Conventions Used in This Manual

  • A command entered at the terminal is shown like this:

    $ command

    The first character on the line is the terminal prompt, and should not be typed. The dollar sign, $, is used as the standard prompt in this manual, although some systems may use a different character.

  • A program (or command) option is printed like this;

  • An option argument is printed like <this>;

  • The name of a variable, or a meta-syntactic variable, is printed like <this>;

  • Literal examples are printed like

    this

  • File names are printed like this.

Additionally, hereinafter a core will explicitly refer to a processor (or CPU) of a computer. This terminology is also consistent with file name formatting for parallel simulation output by FEPX.

Development History

The development of FEPX began in the late 1990s and was lead by Paul Dawson, and involved many members of the Deformation Process Laboratory (DPLab) at Cornell University, USA, until early 2020. An extended development history contributed by Paul Dawson, the lead investigator of the DPLab, can be found in Development History (1990-2020). Ongoing development has since been lead by Matthew Kasemer (Advanced Computational Materials Engineering Laboratory (ACME Lab), The University of Alabama, USA), and Romain Quey (CNRS, Mines Saint-Étienne, France), and involved other members of their respective groups.