MFEM Documentation

MFEM provides two primary git hooks to maintain code quality and repository health:

• pre-commit: Runs astyle on your code before every commit to ensure changes comply with MFEM code styling guidelines.
• pre-push: Runs a suite of tests before every push to verify that file headers are compliant and that no unexpectedly large files have been added to the repository.

Incompressible Schrödinger Flow (ISF) is a $\mathbb{C}^2$-valued Schrödinger equation used to model classical incompressible fluids. Based on Madelung's quantum hydrodynamics, it is particularly effective at capturing thin vortex behaviors.

The method solves the equation $i\hbar \partial\Psi/\partial t = -\frac{1}{2}\hbar^2\Delta\Psi + p\Psi$ subject to the constraints $\text{Re}(\langle\Delta\Psi, i\Psi\rangle) = 0$ and $|\Psi|^2 = 1$.

The AMGF preconditioner is designed for large-scale contact mechanics optimization. It extends classical Algebraic Multigrid (AMG) by adding a targeted small-subspace correction restricted to degrees of freedom involved in active contact constraints.

Why use it? Classical AMG performance typically degrades in late-stage Interior Point (IP) iterations where contact constraints dominate. AMGF improves convergence by addressing this specific subspace.

Requirements:

• To use -amgf, MFEM must be built with a parallel sparse direct solver, specifically MUMPS (MFEM_USE_MUMPS=YES) or CPardiso (MFEM_USE_CPARDISO=YES).
• If no direct solver is available, you can use standard AMG, but it may exhibit slower or stagnating convergence.

To ensure Low-Order Refined (LOR) solvers are effective and spectrally equivalent to their high-order counterparts, you must use specific basis types for the high-order space:

• H1 spaces: Use BasisType::GaussLobatto.
• Nedelec and Raviart-Thomas spaces:
  • Closed basis: Use BasisType::GaussLobatto.
  • Open basis: Use BasisType::IntegratedGLL.

The Incompressible Schrödinger Flow simulation is implemented using a splitting method consisting of the following five steps:

1. Linear Schrödinger equation solver: Solves the base equation.
2. Normalization of the wave function: Ensures the wave function satisfies the required constraints.
3. Pressure projection: Applies the incompressibility constraint.
4. Enforce geometry constraints: Handles boundary or domain-specific constraints.
5. Compute velocity field: Generates the velocity field used for visualization.

The Abs-Value-L(1)-Jacobi preconditioner is designed to work with different assembly levels. The implementation focuses on AssemblyLevel::PARTIAL.

Given the FEM operator structure $A = P^T G^T B^T D B G P$, the standard L(1)-Jacobi is $D_1 = \text{diag}(|A|1)$. Using the triangle inequality, the absolute-value version $D{abs} = \text{diag}(|P^T| |G^T| |B^T| |D| |B| |G| |P|_1)$ is also $A$-convergent.

In MFEM, you can use the AbsMult operator to unwrap a composition of different operators as their absolute-value application. Similar run-time options are available for this purpose.

When using xeus-cling to run MFEM code in a Jupyter notebook, you must explicitly load the MFEM shared library into the cling interpreter. This is done using a #pragma directive at the beginning of your notebook cells.

If the library is not in the default search path, you may also need to use #pragma cling statements to configure the runtime environment to locate your MFEM and GLVis installations.

#pragma cling load("mfem")

To improve your development experience and ensure compliance with MFEM coding standards, you can install recommended git hooks. Running the provided make command creates symlinks from the config/githooks directory to your local .git/hooks directory.

Alternatively, you can enable individual hooks by manually creating symlinks to specific scripts in the config/githooks directory.

make hooks

The miniapp is designed to be extensible. To implement a new topology (e.g., different microstructures), you must implement an appropriate distance metric by creating a child class of MaterialTopology.

After implementing your class, you must swap the instantiation line in generate_random_field.cpp to use your new object instead of the default particle or octet truss implementations.