Input File Reference

Every ExaGOOP simulation requires two input files: a plain-text input parameter file (the *.inp file read by AMReX’s ParmParse) and a particle file containing the initial material point data. Both are typically generated by the PreProcess scripts in each test directory; this page documents every supported parameter so that you can construct or modify them by hand.

Note

Parameters marked required have no default and will cause ExaGOOP to abort if absent. Parameters marked optional have defaults listed in the Default column.

Running the solver

./ExaGOOP<dim>d.<suffix>.ex inputs.inp
# or with MPI:
mpirun -n 4 ./ExaGOOP<dim>d.<suffix>.ex inputs.inp

Particle File Format

ExaGOOP accepts particle files in ASCII (plain text) or HDF5 format. The format is auto-detected from the file extension: .dat or .inp files are treated as ASCII; .h5 files as HDF5.

ASCII format

The file begins with two header lines followed by a comment line listing the column names, then one data row per material point:

dim: <N>
number_of_material_points: <M>
# phase x [y] [z]  vx [vy] [vz]  radius  density  <cm_cols>  [T spheat thermcond heatsrc]
0  0.25  0.0  0.0  0.0  0.0  0.0  0.125  1000.0  ...

Column order depends on dimensionality and the constitutive model:

Column	Type	Description
phase	int	Material phase index (0 for standard deformable material)
x, y, z	real	Initial position coordinates (m). y and z omitted in 1-D and 2-D.
vx, vy, vz	real	Initial velocity components (m/s). vy, vz omitted in lower dimensions.
radius	real	Particle radius used for neighbour searches (m). Typically set to half the inter-particle spacing.
density	real	Material density \(\rho_0\) (kg/m³).
E, nu	real	Young’s modulus (Pa) and Poisson’s ratio (–). Present when constitutive_model.type = elastic.
Bulk_modulus, Gama_pressure, Dynamic_viscosity	real	Bulk modulus (Pa), pressure ratio \(\Gamma\) (–), dynamic viscosity (Pa·s). Present when constitutive_model.type = fluid.
T	real	Initial temperature (K). Present only when compiled with USE_TEMP=1.
spheat	real	Specific heat capacity \(c_p\) (J/(kg·K)). Present only with USE_TEMP=1.
thermcond	real	Thermal conductivity \(k\) (W/(m·K)). Present only with USE_TEMP=1.
heatsrc	real	Volumetric internal heat source \(\dot{q}\) (W/m³). Present only with USE_TEMP=1.

HDF5 format

The HDF5 file stores the same columns as individual 1-D datasets under the root group, plus scalar attributes dim and number_of_material_points. Dataset names are identical to the ASCII column names above.

Input Parameter File

Parameters are grouped into namespaces. Each line has the form:

namespace.parameter_name  =  value

Lines beginning with # are comments.

mpm. namespace — Domain and Grid

Parameter	Type	Default	Description
mpm.prob_lo	real[]	required	Lower corner of the computational domain (m). Three values always; unused dimensions set to 0.
mpm.prob_hi	real[]	required	Upper corner of the computational domain (m).
mpm.ncells	int[]	required	Number of background grid cells per direction. Unused dimensions set to 0.
mpm.max_grid_size	int	8	Maximum AMReX box size. Must be greater than 1.
mpm.is_it_periodic	int[]	required	Periodicity flag per direction: 1 = periodic, 0 = non-periodic.

mpm. namespace — Time Control

Parameter	Type	Default	Description
mpm.final_time	real	required	Simulation end time (s).
mpm.max_steps	int	required	Maximum number of time steps. The run stops at whichever limit is reached first.
mpm.fixed_timestep	int	0	If 1, use a fixed time step supplied via mpm.timestep instead of the CFL-adaptive step.
mpm.timestep	real	—	Fixed time step size (s). Required when fixed_timestep = 1.
mpm.CFL	real	0.1	CFL number for adaptive time stepping. Ignored when fixed_timestep = 1.
mpm.dt_min_limit	real	1e-12	Minimum allowable adaptive time step (s). ExaGOOP aborts if the step falls below this.
mpm.dt_max_limit	real	1.0	Maximum allowable adaptive time step (s).

mpm. namespace — Physics

Parameter	Type	Default	Description
mpm.gravity	real[]	0.0 -9.81 0.0	Gravitational acceleration vector (m/s²).
mpm.alpha_pic_flip	real	0.95	PIC/FLIP blending factor. 0.0 = pure PIC (maximum dissipation), 1.0 = pure FLIP (minimum dissipation).
mpm.order_scheme	int	1	Shape function order: 1 = bilinear, 2 = quadratic B-spline, 3 = cubic B-spline.
mpm.stress_update_scheme	string	USL	Stress update scheme: USL (Update Stress Last) or MUSL (Modified USL).
mpm.calculate_strain_based_on_delta	int	0	If 1, compute strain from incremental displacement rather than velocity gradient.
mpm.mass_tolerance	real	1e-8	Grid nodes whose lumped mass falls below this threshold are excluded from the nodal velocity update.
mpm.applied_strainrate	real	0.0	Uniform applied strain rate (1/s). Applied to the entire domain.
mpm.applied_strainrate_time	real	final_time	Duration over which the applied strain rate is active (s).
mpm.external_loads	int	0	If 1, apply a uniform body force to the slab region defined below.
mpm.force_slab_lo	real[]	—	Lower corner of the force slab (m). Required when external_loads = 1.
mpm.force_slab_hi	real[]	—	Upper corner of the force slab (m). Required when external_loads = 1.
mpm.extforce	real[]	—	Force per unit volume applied within the slab (N/m³). Required when external_loads = 1.

mpm. namespace — Material Points

Parameter	Type	Default	Description
mpm.particle_file	string	mpm_particles.dat	Path to the particle input file. Used when use_autogen = 0.
mpm.num_redist	int	10	Redistribute particles across MPI ranks every N time steps.
mpm.use_autogen	int	0	If 1, generate particles internally from the autogen parameters below instead of reading a file.

When use_autogen = 1, the following parameters define the particle block:

Parameter	Type	Default	Description
mpm.mincoords_autogen	real[]	required	Lower corner of the autogen particle block (m).
mpm.maxcoords_autogen	real[]	required	Upper corner of the autogen particle block (m).
mpm.vel_autogen	real[]	required	Initial velocity for all autogen particles (m/s).
mpm.ppc	int[]	—	Particles per cell per direction, e.g. 2 2 2 for eight particles per cell in 3-D.
mpm.multi_part_per_cell_autogen	int	1	If 1, place multiple particles per cell (uses ppc); if 0, one particle per cell.
mpm.constmodel_autogen	int	1	Constitutive model ID: 0 = linear elastic, 1 = compressible fluid.
mpm.dens_autogen	real	1000.0	Density of autogen particles (kg/m³).
mpm.E_autogen	real	1e9	Young’s modulus for elastic model (Pa).
mpm.nu_autogen	real	0.1	Poisson’s ratio for elastic model (–).
mpm.bulkmod_autogen	real	0.0	Bulk modulus for fluid model (Pa).
mpm.Gama_pres_autogen	real	1.4	Pressure ratio \(\Gamma\) for the fluid equation of state (–).
mpm.visc_autogen	real	0.001	Dynamic viscosity for fluid model (Pa·s).
mpm.T_autogen	real	0.0	Initial temperature of autogen particles (K). USE_TEMP only.
mpm.cp_autogen	real	1.0	Specific heat capacity (J/(kg·K)). USE_TEMP only.
mpm.thermcond_autogen	real	1.0	Thermal conductivity (W/(m·K)). USE_TEMP only.
mpm.heatsrc_autogen	real	0.0	Volumetric internal heat source (W/m³). USE_TEMP only.

mpm. namespace — Output

Parameter	Type	Default	Description
mpm.write_output_time	real	final_time / 10	Interval between solution snapshots (s).
mpm.screen_output_time	real	write_output_time / 10	Interval between screen (terminal) output lines (s).
mpm.prefix_particlefilename	string	plt	Directory/file prefix for particle output plotfiles (plt*).
mpm.prefix_gridfilename	string	plt	Directory/file prefix for nodal grid output plotfiles (nplt*).
mpm.prefix_densityfilename	string	plt	Directory/file prefix for density output plotfiles.
mpm.prefix_checkpointfilename	string	chk	Directory/file prefix for checkpoint files used to restart a run.
mpm.prefix_asciifilename	string	matpnt	Directory/file prefix for ASCII material point output files.
mpm.diagnostic_output_folder	string	./Diagnostics/	Directory for diagnostic output files.
mpm.num_of_digits_in_filenames	int	6	Number of zero-padded digits in output file step indices.
mpm.write_ascii	int	0	If 1, write ASCII material point files alongside the plotfiles.

mpm. namespace — Diagnostics

Diagnostics are activated by setting mpm.print_diagnostics = 1.

Parameter	Type	Default	Description
mpm.print_diagnostics	int	0	Master switch: set to 1 to enable all diagnostic output.
mpm.do_calculate_tke_tse	int	0	If 1, compute and write total kinetic and strain energies.
mpm.do_calculate_mwa_velcomp	int	0	If 1, compute and write mass-weighted average velocity components.
mpm.do_calculate_mwa_velmag	int	0	If 1, compute and write mass-weighted average velocity magnitude.
mpm.do_calculate_minmaxpos	int	0	If 1, compute and write the minimum and maximum particle positions.
mpm.write_diag_output_time	real	write_output_time	Interval between diagnostic output writes (s).

mpm. namespace — Level-Set Output

Parameter	Type	Default	Description
mpm.levset_output	int	0	If 1, write level-set field plotfiles for visualisation.
mpm.levset_smoothfactor	real	1.0	Smoothing factor applied to the level-set signed-distance field.
mpm.levset_gridratio	int	1	Refinement ratio for the level-set grid relative to the background grid.

mpm. namespace — Momentum Boundary Conditions

Momentum BCs are specified per face. Valid face identifiers are xlo, xhi, ylo, yhi, zlo, zhi.

mpm.bc_<face>_mom  =  <type>

Valid <type> values:

Value	Behaviour
slip	Slip wall (default): zero normal velocity, unconstrained tangential velocity.
noslip	No-slip wall: all velocity components set to zero (or the prescribed wall velocity).
partialslip	Partial-slip wall: tangential velocity damped by friction coefficient wall_mu.
outflow	Outflow: material points exiting through this face are removed.
periodic	Periodic. Must be matched with the opposite face and mpm.is_it_periodic = 1 in that direction.

Additional sub-parameters for mpm.bc_<face>_mom:

Parameter	Type	Default	Description
mpm.bc_<face>_mom.wall_vel	real[]	0 0 0	Prescribed constant wall velocity (m/s) for noslip or partialslip walls.
mpm.bc_<face>_mom.wall_mu	real	0.0	Friction coefficient for partialslip walls (–).
mpm.bc_<face>_mom.udf_lib	string	—	Path to the shared library implementing a UDF velocity profile. Both udf_lib and udf_func must be supplied together.
mpm.bc_<face>_mom.udf_func	string	—	Name of the C-linkage function exported by the UDF shared library. See UDF Moving Wall Boundary Conditions for the required function signature.

mpm. namespace — Temperature Boundary Conditions (USE_TEMP only)

Temperature BCs follow the same per-face pattern as momentum BCs.

mpm.bc_<face>_temp  =  <type>

Valid <type> values:

Value	Behaviour
adiabatic	Adiabatic (default): zero heat flux through the face.
dirichlet	Fixed wall temperature. Requires T_wall.
heatflux	Prescribed heat flux. Requires flux.
convective	Newton cooling law: \(q = h (T_\text{wall} - T_\infty)\). Requires h and T_inf.
periodic	Periodic (must be paired with mpm.is_it_periodic = 1 in that direction).

Additional sub-parameters for mpm.bc_<face>_temp:

Parameter	Type	Default	Description
mpm.bc_<face>_temp.T_wall	real	0.0	Wall temperature for dirichlet BC (K).
mpm.bc_<face>_temp.flux	real	0.0	Prescribed heat flux for heatflux BC (W/m²). Positive flux into the domain.
mpm.bc_<face>_temp.h	real	0.0	Convective heat transfer coefficient for convective BC (W/(m²·K)).
mpm.bc_<face>_temp.T_inf	real	0.0	Ambient temperature for convective BC (K).
mpm.bc_<face>_temp.udf_lib	string	—	Path to a UDF shared library for a custom temperature profile.
mpm.bc_<face>_temp.udf_func	string	—	Function name in the UDF temperature shared library.

amr. namespace — Restart

Parameter	Type	Default	Description
amr.restart_checkfile	string	""	Path to a checkpoint directory to restart the simulation from. Leave empty for a fresh start.

eb2. namespace — Embedded Boundaries (USE_EB only)

Parameter	Type	Default	Description
eb2.body_names	string[]	—	Space-separated list of body names. Each name becomes the ParmParse namespace for that body’s parameters. If omitted, ExaGOOP falls back to legacy single-body mode reading from the eb2. namespace directly.

Per-body namespace <body_name>. (USE_EB only)

Replace <body_name> with the name listed in eb2.body_names.

Common parameters (all geometry types):

Parameter	Type	Default	Description
<name>.geom_type	string	required	Shape type: sphere, plane, cylinder, box, stl, udf_cpp, wedge_hopper.
<name>.ls_refinement	int	1	Level-set grid refinement ratio relative to the background grid. Higher values improve surface accuracy.
<name>.levelset_mom	string	noslipwall	Momentum BC on the body surface: noslipwall, slipwall, or partialslip.
<name>.lset_wall_mu	real	0.0	Friction coefficient for partialslip body surfaces (–).
<name>.lset_wall_vel	real[]	0 0 0	Constant wall velocity imposed on the body surface (m/s).
<name>.temp_bc_type	string	adiabatic	Temperature BC on the body surface: isothermal, adiabatic, heatflux, convective. USE_TEMP only.
<name>.lset_T_wall	real	0.0	Isothermal wall temperature (K). USE_TEMP only.
<name>.lset_heat_flux	real	0.0	Heat flux through the body surface (W/m²). USE_TEMP only.
<name>.lset_h_conv	real	0.0	Convective heat transfer coefficient (W/(m²·K)). USE_TEMP only.
<name>.lset_T_inf	real	0.0	Ambient temperature for convective BC (K). USE_TEMP only.

Sphere (geom_type = sphere):

Parameter	Type	Default	Description
<name>.sphere_radius	real	required	Sphere radius (m).
<name>.sphere_center	real[]	required	Centre coordinates (m).
<name>.sphere_has_fluid_inside	bool	false	If true, fluid occupies the interior of the sphere; the solid body is outside.

Plane (geom_type = plane):

Parameter	Type	Default	Description
<name>.plane_point	real[]	required	A point on the plane (m).
<name>.plane_normal	real[]	required	Outward normal vector pointing into the fluid domain.
<name>.plane_has_fluid_inside	bool	false	Orientation flag. See sphere_has_fluid_inside.

Cylinder (geom_type = cylinder):

Parameter	Type	Default	Description
<name>.cylinder_radius	real	required	Cylinder radius (m).
<name>.cylinder_center	real[]	required	Axis centre coordinates (m).
<name>.cylinder_height	real	1.0	Cylinder height along the axis direction (m).
<name>.cylinder_direction	int	2	Axis direction: 0 = x, 1 = y, 2 = z.
<name>.cylinder_has_fluid_inside	bool	false	Orientation flag.

Box (geom_type = box):

Parameter	Type	Default	Description
<name>.box_lo	real[]	required	Lower corner of the box (m).
<name>.box_hi	real[]	required	Upper corner of the box (m).
<name>.box_has_fluid_inside	bool	false	Orientation flag.

STL geometry (geom_type = stl):

Parameter	Type	Default	Description
<name>.stl_file	string	required	Path to an STL surface mesh file describing the body geometry.

UDF implicit function (geom_type = udf_cpp):

Parameter	Type	Default	Description
<name>.udf_so_file	string	required	Path to a shared library exporting a signed-distance function for the body surface.

Wedge hopper (geom_type = wedge_hopper, 3-D only):

Parameters are read from the wedge_hopper. namespace rather than the body namespace:

Parameter	Type	Default	Description
wedge_hopper.exit_size	real	required	Width of the hopper exit opening (m).
wedge_hopper.bin_size	real	required	Width of the hopper bin above the funnel (m).
wedge_hopper.funnel_height	real	required	Height of the converging funnel section (m).
wedge_hopper.vertical_offset	real	domain centre	Vertical position of the hopper centre (m).

Minimal Working Example

The following input file runs a 1-D elastic bar vibration with 30 cells, no gravity, and fixed boundary conditions at both ends:

#------------------------------
# Domain
#------------------------------
mpm.prob_lo        = 0.0 0.0 0.0
mpm.prob_hi        = 30.0 0.0 0.0
mpm.ncells         = 30 0 0
mpm.max_grid_size  = 16
mpm.is_it_periodic = 0

#------------------------------
# Time control
#------------------------------
mpm.final_time  = 50.0
mpm.max_steps   = 5000000
mpm.CFL         = 0.1

#------------------------------
# Material points
#------------------------------
mpm.particle_file = mpm_particles.dat

#------------------------------
# Output
#------------------------------
mpm.write_output_time  = 0.5
mpm.screen_output_time = 0.001
mpm.prefix_particlefilename = "results/plt"
mpm.prefix_gridfilename     = "results/nplt"

#------------------------------
# Numerics
#------------------------------
mpm.order_scheme           = 1
mpm.alpha_pic_flip         = 1.0
mpm.stress_update_scheme   = MUSL
mpm.gravity                = 0.0 0.0 0.0

#------------------------------
# Boundary conditions
#------------------------------
mpm.bc_xlo_mom = noslip
mpm.bc_xhi_mom = noslip