Quick Start#
A first simulation in five minutes: a polycrystal of 20 grains pulled to 1 % strain, the first tutorial (Simple simulation), whose input files are installed with FEPX.
Install FEPX (Installation), and Neper (https://neper.info) to visualize the results.
Copy the case and go to its directory. It holds the mesh,
simulation.msh(made by Neper: 10-node tetrahedra, one element set per grain), and the configuration,simulation.cfg(installed with the package in/usr/share/doc/fepx/examples/; from a source build, inshare/doc/fepx/examples/of the installation directory):$ cp -r /usr/share/doc/fepx/examples/simple_simulation . $ cd simple_simulation
Read the configuration: an fcc material (elastic constants, slip kinetics, saturation hardening), velocity conditions on the faces, two steps to 5 s and 10 s, and the variables to write:
## FEPX tutorial "Simple simulation": a 20-grain fcc polycrystal in the unit cube pulled ## along z at 0.001 mm/s, the conditions given node set by node set, two steps of 5 s. ## Material number_of_phases 1 phase 1 crystal_type FCC model crystal_plasticity c11 245.0e3 c12 155.0e3 c44 62.5e3 m 0.05 gammadot_0 1.0 tau_0 210.0 hardening saturation_isotropic h_0 200.0 tau_s 330.0 n 1.0 ## Loading boundary_conditions general set_bc vel z0 z 0 set_bc vel z1 z 0.001 set_bc vel x0y0z0 x 0 y 0 set_bc vel x1y0z0 y 0 number_of_steps 2 target_time 5.0 10.0 dtime 1.0 1.0 ## Output print coo print ori print stress print strain print forces
Run FEPX on 4 processes (the mesh has 8 partitions: FEPX says so and distributes it evenly):
$ mpirun -np 4 fepx
======================== F E P X =========================== Info : A finite element software package for polycrystal plasticity. Info : Version 3.0.0-dev (git 755da754, 11-06-2026) Info : Built with: GCC 15.2.0|Open MPI 5.0.10|HDF5 1.14.6 Info : Running on 4 ranks. Info : <https://fepx.info> Info : Copyright (C) 1996-2026, and MIT licensed, by the FEPX authors. Info : --------------------------------------------------------------- Info : Loading simulation... Info : [i] Parsing file `simulation.cfg'... Info : [i] Parsed file `simulation.cfg'. Info : [i] Parsing file `simulation.msh'... Info : [i] Parsed file `simulation.msh'. Info : - Material parameters: Info : > Number of phases: 1 Info : > Phase 1: fcc, crystal_plasticity Info : . c11: 2.4500E+05 MPa Info : . c12: 1.5500E+05 MPa Info : . c44: 6.2500E+04 MPa Info : . m: 5.0000E-02 Info : . gammadot_0: 1.0000E+00 1/s Info : . hardening: saturation_isotropic Info : . tau_0: 2.1000E+02 MPa Info : . h_0: 2.0000E+02 MPa Info : . tau_s: 3.3000E+02 MPa Info : . n: 1.0000E+00 Info : . saturation_evolution: off (def.) Info : . cyclic_hardening: off (def.) Info : . precipitate_strengthening: off (def.) Info : - Loading: boundary_conditions general, 2 steps Info : > Step 1: t = 0.0000E+00 -> 5.0000E+00 s, 5 increments Info : > Step 2: t = 5.0000E+00 -> 1.0000E+01 s, 5 increments Info : - Options other than the defaults: (none) Info : - Output: coo ori stress strain forces (format ascii) Info : - Mesh parameters: Info : > Node number: 4008 Info : > Elt number: 2453 (10-node tetrahedra) Info : > Elsets: 20; partitions: 4 Info : - Partitioning: 4 ranks Info : > Elements per rank: 613 to 614 Info : > Ghost nodes per rank: 146 to 167 (626 in total) Info : > Neighbors per rank: 3 to 3 Info : [o] Writing results to `simulation.sim'... Info : Initializing simulation... Info : - Elastic step of 1.1351E-02 s (step 1) Info : > Iteration 1 (SA): R = 2.5329E+00 (543 CG iterations) Info : > Iteration 2 (SA): R = 1.5030E-05 (539 CG iterations) Info : > Converged in 2 iterations (0.648 s) Info : Running step 1... Info : - Increment 1: t = 1.0000E+00 s, dt = 9.8865E-01 s Info : > Iteration 1 (SA): R = 7.1922E-04 (552 CG iterations) Info : > Iteration 2 (NR): R = 6.3443E-07 (562 CG iterations) Info : > Converged in 2 iterations (0.776 s) [...] Info : Final step terminated. Simulation completed successfully. Info : [o] Wrote results to `simulation.sim'. Info : - Increments: 10 Info : - Global iterations: 47 (22 NR) Info : - CG iterations: 32537 Info : - Warnings issued: 0 Info : - Wall time per phase: Info : > Input and setup: 0.054 s Info : > Initialization: 0.655 s Info : > Increments: 21.166 s Info : . Element and material work: 13.250 s Info : . CG: 7.833 s Info : . Other: 0.083 s Info : > Output: 0.330 s Info : Elapsed time: 22.205 s ========================================================================
The results are in the simulation directory,
simulation.sim:simulation.sim |-- inputs | |-- simulation.cfg | `-- simulation.msh `-- results |-- elts | |-- ori | | |-- ori.step0 | | |-- ori.step1 | | `-- ori.step2 | |-- strain | | |-- strain.step0 | | |-- strain.step1 | | `-- strain.step2 | `-- stress | |-- stress.step0 | |-- stress.step1 | `-- stress.step2 |-- forces | |-- x0 | |-- x1 | |-- y0 | |-- y1 | |-- z0 | `-- z1 |-- mesh | |-- strain | | |-- strain.step0 | | |-- strain.step1 | | `-- strain.step2 | `-- stress | |-- stress.step0 | |-- stress.step1 | `-- stress.step2 `-- nodes `-- coo |-- coo.step0 |-- coo.step1 `-- coo.step2Neper reads it: for example, the volume averages of the stress and the strain at the end of each step are written by
$ neper -S simulation.sim -resmesh stress,strain
and the stress field of the last step, on the deformed mesh, is plotted with
neper -V(the commands are in Simple simulation):
Fig. 1 Stress \(\sigma_{33}\) at 1 % strain.#
Next: Configuration File (simulation.cfg) describes the configuration file, Running a Simulation the runs, and Tutorials gives more examples.