Hydrogen SI Engine Dynamic-Mesh Case
====================================

OpenFOAM version
----------------
This case is prepared for OpenFOAM v2406 (OpenCFD distribution). It uses a
custom dynamic-mesh reacting solver named `reactingDyMFoam`, derived from
`reactingFoam` and modified to update the dynamic mesh during the PIMPLE loop.

Case description
----------------
This is a simplified single-cylinder hydrogen spark-ignition engine case. The
domain contains the piston, cylinder liner, and cylinder head. Piston movement
is prescribed from a crank-slider displacement table, while combustion is
modelled as laminar hydrogen-air combustion with a global one-step Arrhenius
reaction.

Important directories and files
-------------------------------
- `0/`       Initial and boundary-condition fields, including `pointDisplacement`.
- `constant/` Physical models, reaction data, mesh-motion settings, and mesh files.
- `system/`  Run controls, numerical schemes, solver controls, and parallel settings.
- `Allrun`   Automates mesh creation, decomposition, parallel execution, and reconstruction.
- `Allclean` Removes generated results and resets the case.
- `crankAngle.py` Generates the piston position table used by the dynamic mesh.

Required OpenFOAM configuration
-------------------------------
The following case files must be present and consistent with OpenFOAM v2406:

- `system/controlDict` must specify:

    application     reactingDyMFoam;

- `constant/dynamicMeshDict` must enable dynamic mesh motion, using
  `dynamicMotionSolverFvMesh` and the selected motion solver, such as
  `displacementLaplacian`.

- `0/pointDisplacement` must define the moving `piston` patch and fixed `head`
  patch. The piston boundary can read the tabulated displacement profile using
  a `uniformFixedValue` table.

- `constant/thermophysicalProperties` must define the reacting mixture with
  `hePsiThermo`, `reactingMixture`, `janaf` thermodynamics, `sutherland`
  transport, and `N2` as the inert species.

- `constant/chemistryProperties` and `constant/reactions` must define the
  hydrogen chemistry model. The documented setup uses an ODE chemistry solver
  with `RKCK45`, and the global reaction `2H2 + O2 -> 2H2O`.

Compiling the solver
--------------------
The solver must be compiled only if `reactingDyMFoam` is not already available
in the OpenFOAM installation or user application directory.

1. Load the OpenFOAM v2406 environment:

    source /path/to/OpenFOAM-v2406/etc/bashrc

2. Go to the directory that contains the custom `reactingDyMFoam` source code,
   including its `Make/files` and `Make/options` files.

3. Compile the solver:

    wmake

4. Confirm that it is available:

    which reactingDyMFoam

The solver build configuration must link the required dynamic-mesh libraries,
and the executable should be placed in `$FOAM_USER_APPBIN` (or the configured
OpenFOAM application binary location).

Preparing piston motion
-----------------------
The supplied `crankAngle.py` script generates the piston displacement table
for a complete 720-degree, four-stroke engine cycle. It uses:

- Stroke: 0.086 m
- Connecting rod length: 0.143 m
- Crank-angle increment: 1 degree
- Default speed: 1500 RPM

Generate the table with:

    python3 crankAngle.py > constant/pistonPos.dat

If a different speed is required, edit the `RPM` variable in
`crankAngle.py`, regenerate `constant/pistonPos.dat`, and ensure that
`0/pointDisplacement` includes or reads this file.

Running the case
----------------
Before the first run, load OpenFOAM and make the helper scripts executable:

    source /path/to/OpenFOAM-v2406/etc/bashrc
    chmod +x Allrun Allclean

Run the complete parallel workflow:

    ./Allrun

`Allrun` performs the following operations:

1. Restores the initial `0/` directory.
2. Creates `foam.foam` for ParaView/paraFoam access.
3. Generates the mesh using `blockMesh`.
4. Runs `topoSet`.
5. Decomposes the case using `decomposePar`.
6. Runs the solver specified in `controlDict` in parallel.
7. Reconstructs the parallel results using `reconstructPar`.

The number of processors is controlled by `system/decomposeParDict`. Ensure
that the selected parallel decomposition is suitable for the available CPU
resources before launching the case.

Manual run sequence
-------------------
If the individual commands need to be run manually, use:

    restore0Dir
    blockMesh
    topoSet
    decomposePar
    mpirun -np <N> reactingDyMFoam -parallel
    reconstructPar

Replace `<N>` with the number of subdomains defined in
`system/decomposeParDict`.

Cleaning the case
-----------------
To remove generated time directories, processor directories, and other run
outputs, use:

    ./Allclean

The supplied cleanup script calls OpenFOAM's `cleanCase0` helper.

Post-processing
---------------
After reconstruction, open the case in ParaView with:

    paraFoam

or open the generated `foam.foam` file. Examine mesh deformation, piston
motion, in-cylinder pressure, temperature, and H2/O2/H2O species fields.

Stability notes
---------------
Moving-mesh hydrogen combustion can be sensitive to stiff chemistry, excessive
Courant number, and mesh distortion. Use adaptive time stepping, keep the
Courant number controlled, and check mesh quality throughout the run. The
reported chemistry configuration uses `RKCK45`, an initial chemical time step
of `1e-08`, and a maximum chemistry time step of `1e-06` for improved
robustness.
