.. _input_reference: 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 ------------------ .. code-block:: bash ./ExaGOOPd..ex inputs.inp # or with MPI: mpirun -n 4 ./ExaGOOPd..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: .. code-block:: text dim: number_of_material_points: # phase x [y] [z] vx [vy] [vz] radius density [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: .. list-table:: :header-rows: 1 :widths: 20 15 65 * - 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 :math:`\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 :math:`\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 :math:`c_p` (J/(kg·K)). Present only with ``USE_TEMP=1``. * - ``thermcond`` - real - Thermal conductivity :math:`k` (W/(m·K)). Present only with ``USE_TEMP=1``. * - ``heatsrc`` - real - Volumetric internal heat source :math:`\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 -------------------------------------- .. list-table:: :header-rows: 1 :widths: 32 10 15 43 * - 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 ------------------------------------ .. list-table:: :header-rows: 1 :widths: 32 10 15 43 * - 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 ------------------------------- .. list-table:: :header-rows: 1 :widths: 32 10 15 43 * - 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 -------------------------------------- .. list-table:: :header-rows: 1 :widths: 32 10 15 43 * - 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: .. list-table:: :header-rows: 1 :widths: 32 10 15 43 * - 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 :math:`\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 ----------------------------- .. list-table:: :header-rows: 1 :widths: 32 10 15 43 * - 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``. .. list-table:: :header-rows: 1 :widths: 36 10 12 42 * - 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 ----------------------------------------- .. list-table:: :header-rows: 1 :widths: 32 10 15 43 * - 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``. .. code-block:: text mpm.bc__mom = Valid ```` values: .. list-table:: :header-rows: 1 :widths: 25 75 * - 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__mom``: .. list-table:: :header-rows: 1 :widths: 36 10 12 42 * - Parameter - Type - Default - Description * - ``mpm.bc__mom.wall_vel`` - real[] - ``0 0 0`` - Prescribed constant wall velocity (m/s) for ``noslip`` or ``partialslip`` walls. * - ``mpm.bc__mom.wall_mu`` - real - 0.0 - Friction coefficient for ``partialslip`` walls (–). * - ``mpm.bc__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__mom.udf_func`` - string - — - Name of the C-linkage function exported by the UDF shared library. See :ref:`udf_moving_wall` for the required function signature. ``mpm.`` namespace — Temperature Boundary Conditions (``USE_TEMP`` only) -------------------------------------------------------------------------- Temperature BCs follow the same per-face pattern as momentum BCs. .. code-block:: text mpm.bc__temp = Valid ```` values: .. list-table:: :header-rows: 1 :widths: 20 80 * - 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: :math:`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__temp``: .. list-table:: :header-rows: 1 :widths: 36 10 12 42 * - Parameter - Type - Default - Description * - ``mpm.bc__temp.T_wall`` - real - 0.0 - Wall temperature for ``dirichlet`` BC (K). * - ``mpm.bc__temp.flux`` - real - 0.0 - Prescribed heat flux for ``heatflux`` BC (W/m²). Positive flux into the domain. * - ``mpm.bc__temp.h`` - real - 0.0 - Convective heat transfer coefficient for ``convective`` BC (W/(m²·K)). * - ``mpm.bc__temp.T_inf`` - real - 0.0 - Ambient temperature for ``convective`` BC (K). * - ``mpm.bc__temp.udf_lib`` - string - — - Path to a UDF shared library for a custom temperature profile. * - ``mpm.bc__temp.udf_func`` - string - — - Function name in the UDF temperature shared library. ``amr.`` namespace — Restart ------------------------------ .. list-table:: :header-rows: 1 :widths: 32 10 15 43 * - 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) ----------------------------------------------------------- .. list-table:: :header-rows: 1 :widths: 32 10 15 43 * - 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 ``.`` (``USE_EB`` only) ------------------------------------------------------ Replace ```` with the name listed in ``eb2.body_names``. **Common parameters (all geometry types):** .. list-table:: :header-rows: 1 :widths: 32 10 15 43 * - Parameter - Type - Default - Description * - ``.geom_type`` - string - **required** - Shape type: ``sphere``, ``plane``, ``cylinder``, ``box``, ``stl``, ``udf_cpp``, ``wedge_hopper``. * - ``.ls_refinement`` - int - 1 - Level-set grid refinement ratio relative to the background grid. Higher values improve surface accuracy. * - ``.levelset_mom`` - string - ``noslipwall`` - Momentum BC on the body surface: ``noslipwall``, ``slipwall``, or ``partialslip``. * - ``.lset_wall_mu`` - real - 0.0 - Friction coefficient for ``partialslip`` body surfaces (–). * - ``.lset_wall_vel`` - real[] - ``0 0 0`` - Constant wall velocity imposed on the body surface (m/s). * - ``.temp_bc_type`` - string - ``adiabatic`` - Temperature BC on the body surface: ``isothermal``, ``adiabatic``, ``heatflux``, ``convective``. ``USE_TEMP`` only. * - ``.lset_T_wall`` - real - 0.0 - Isothermal wall temperature (K). ``USE_TEMP`` only. * - ``.lset_heat_flux`` - real - 0.0 - Heat flux through the body surface (W/m²). ``USE_TEMP`` only. * - ``.lset_h_conv`` - real - 0.0 - Convective heat transfer coefficient (W/(m²·K)). ``USE_TEMP`` only. * - ``.lset_T_inf`` - real - 0.0 - Ambient temperature for convective BC (K). ``USE_TEMP`` only. **Sphere** (``geom_type = sphere``): .. list-table:: :header-rows: 1 :widths: 32 10 15 43 * - Parameter - Type - Default - Description * - ``.sphere_radius`` - real - **required** - Sphere radius (m). * - ``.sphere_center`` - real[] - **required** - Centre coordinates (m). * - ``.sphere_has_fluid_inside`` - bool - ``false`` - If ``true``, fluid occupies the interior of the sphere; the solid body is outside. **Plane** (``geom_type = plane``): .. list-table:: :header-rows: 1 :widths: 32 10 15 43 * - Parameter - Type - Default - Description * - ``.plane_point`` - real[] - **required** - A point on the plane (m). * - ``.plane_normal`` - real[] - **required** - Outward normal vector pointing into the fluid domain. * - ``.plane_has_fluid_inside`` - bool - ``false`` - Orientation flag. See ``sphere_has_fluid_inside``. **Cylinder** (``geom_type = cylinder``): .. list-table:: :header-rows: 1 :widths: 32 10 15 43 * - Parameter - Type - Default - Description * - ``.cylinder_radius`` - real - **required** - Cylinder radius (m). * - ``.cylinder_center`` - real[] - **required** - Axis centre coordinates (m). * - ``.cylinder_height`` - real - 1.0 - Cylinder height along the axis direction (m). * - ``.cylinder_direction`` - int - 2 - Axis direction: ``0`` = x, ``1`` = y, ``2`` = z. * - ``.cylinder_has_fluid_inside`` - bool - ``false`` - Orientation flag. **Box** (``geom_type = box``): .. list-table:: :header-rows: 1 :widths: 32 10 15 43 * - Parameter - Type - Default - Description * - ``.box_lo`` - real[] - **required** - Lower corner of the box (m). * - ``.box_hi`` - real[] - **required** - Upper corner of the box (m). * - ``.box_has_fluid_inside`` - bool - ``false`` - Orientation flag. **STL geometry** (``geom_type = stl``): .. list-table:: :header-rows: 1 :widths: 32 10 15 43 * - Parameter - Type - Default - Description * - ``.stl_file`` - string - **required** - Path to an STL surface mesh file describing the body geometry. **UDF implicit function** (``geom_type = udf_cpp``): .. list-table:: :header-rows: 1 :widths: 32 10 15 43 * - Parameter - Type - Default - Description * - ``.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: .. list-table:: :header-rows: 1 :widths: 32 10 15 43 * - 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: .. code-block:: text #------------------------------ # 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