Lethe v1.0.4 compatible wth deal.ii 9.7

The Lethe v1.0.4 requires the latest major release of the deal.II library (deal.ii v9.7).

As part of the v1.0 release, the major components of this version are detailed in the following Journal Article (which is available in open-access):
https://doi.org/10.1016/j.cpc.2025.109880

Lethe v1.0.4 introduces some key new features and bug fixes including:

• A first version of our Discontinuous Petrov-Galerkin solver for the time-harmonic Maxwell equations. This solver is still experimental.
• A major refactoring of the box refinement capabilities. The usage of multiple box is now supported.
• A new sub simulation control capabilities to enable advanced dynamic time-stepping in unresolved CFD-DEM simulations.
• Adequate treatment of buoyancy forces in VOF simulations.
• A new way to control the dynamic time step in transient VOF simulations using the capillary time-step restriction.
• Significant improvement to the Algebraic redistanciation approach for VOF simulations.
• Addition of missing terms in the deviatoric stress tensor of the VANS equations for cases where the velocity field is non divergence-free

The full Changelog is here:

[Master] - 2026/02/19

Fixed

• MINOR This PR changes the outputted liquid fraction table in a scientific notation format and adds the missing post-processing parameters to the user documentation. #1917

[Master] - 2026/02/18

Changed

• MINOR Changed the 2D dam break example to use geometric redistanciation instead of the projection method. The results do not change, but we would rather users use this method instead of the projection method. The documentation was updated accordingly. #1916

[Master] - 2026/02/17

Fixed

• MINOR Changed the way the waveguide inlet boundary conditions are computed for the time‑harmonic Maxwell solver: we now define an orthonormal local basis from the input quadrilateral, compute the excitation in that local frame, then map it back to the global frame. This fixes cases where the local basis is left‑handed by correctly accounting for the magnetic field's pseudovector behaviour. #1896

Added

• MINOR This PR adds the velocity gradient field to the post-processor data structure. #1913

• MINOR This PR improves the Doxygen documentation and the comments for the VANS assemblers. The VANS assemblers were correctly documented, but the formulas of the assemblers were still written in C++ style instead of in LaTeX style which made their rendering on the doxygen very poor. This PR improves this by formatting in LaTeX. #1909

[Master] - 2026/02/16

Added

• MINOR This PR adds a function to compute the workload imbalance of mortar cells. When verbosity is set to extra verbose in the mortar subsection, the function mortar_workload_imbalance is called. Then, the computed workload imbalance is printed, as well as the minimum and maximum number of mortar cells per process. #1910

Fixed

• MINOR The store_candidates function of the broad search stores the potential contact candidates of a particle. It uses a pre-allocated vector to store them. However, this pre-allocated vector was allocated and then copied into the storage container. Furthermore, the hash function for the map was used twice, once for the search and then once for the emplace. This PR fixes this by using a different logic. First, we use try_emplace to insert an empty vector into the map. If the insertion has occured, we reserve the memory for that vector locally inside of the map. This prevents both the double usage of the hash function and the double vector allocation. The performance increase in some of the test cases I have tried is quite significant (approx. 10% faster than it used to be). This does not change anything to any of the results since the order of operations is preserved. #1911

Added

• MINOR This PR adds all the parameter files and scripts used to run the cases presented in the CLS reinitialization methods article (rising bubble 3D, capillary migration, and Rayleigh-Plateau instability). The files are as they were used, so there is place for improvement (portability between simulation). The documentation of the examples will be added later. #1912

Changed

• MINOR This PR improves the Doxygen documentation interface. We integrate Doxygen Awesome CSS with dark/light mode support as the base theme and extend it with several enhancements:

  • Add a GitHub widget with live repository statistics (stars and forks).
  • Update the main page graph to include the latest applications, highlighted in blue.
  • Implement responsive layout adjustments to improve content organization across window sizes.
  • Fix the header (including the search bar) to the top of the page for persistent navigation (no more need to scroll back up the page).
  • Dynamically display the current Lethe version in the project title (read from CMakeLists.txt).
  • Add a CHAOS logo to the footer with copyright and auto-updating year.
  • Add direct links to the Lethe project page and the CHAOS Laboratory website in the navigation bar.

  All features are compatible with both dark and light modes. #1908

[Master] - 2026/02/13

Fixed

• MINOR There were missing timer subsections in some of the functions executed when mortar is enabled. This PR fixes this by adding timer subsections where mortar entries are added in the matrix and RHS assembler. #1907

[Master] - 2026/02/11

Added

• MAJOR This PR adds the option to have up to 5 different refinement boxes. number of refinement boxes declares the number of refinement boxes and each box has its own subsection (box #). Within the subsection, additional refinement defines the number of additional times the simulation triangulation is refined within the box region. An alias for additional refinement with its previous name initial refinement prevents compatibility issues. A mesh subsection, within the box # subsection, defines the parameters of the refinement box mesh. Within the latter, users can define scaling, translation and rotation of the refinement mesh. This subsection contains the same parameters as the simulation mesh subsection. Two application tests (2D and 3D) added to lethe-fluid protect the software against regressions.

  This PR also adds a new function apply_mesh_transformation to scale, translate, and rotate the meshes in the listed order.

  Finally, this PR updates all concerned examples, tests and documentation. #1901

Added/Fixed

• MAJOR This PR introduces a sub simulation control structure that controls the DEM iterations within CFD-DEM iterations. This structure is fully implemented, but is not fully used yet in the solvers to prevent changing the test outcome in this PR. Essentially, the sub simulation control is responsible for calculating the dem time step in a unified fashion and monitoring the DEM iterations. It also enabled to find a bug which is that the DEM time-step was always wrongly calculated when BDF2 simulations were carried out because the value of the CFD time-step taken to calculate the DEM time-step was not the correct one in the first two iterations. This PR fixes this, which now leads to the adequate results. This is why the outcome of two tests has changed. A follow-up PR will be done to adequately integrate the sub simulation control everywhere in the CFD-DEM solver and ensure that no internal variables are used to store the dem time step, iteration, etc. #1900

[Master] - 2026/02/09

Added

• MINOR This PR adds the option to declare a custom distribution as volume or number weighted. In addition, an option was added to the "custom distribution" allowing the sampled diameter values to be interpolated between input data points. Finally, the custom distribution diameter values and probability values can be defined using the probability density function (PDF) or the cumulative density function (CDF) of the particle size distribution (PSD). #1892

Changed

• MINOR Containers for the Lagrangian particle properties are changed from std::unordered_map to std::vectors. #1892

[Master] - 2026/02/07

Changed

• MAJOR This PR updates the project version to the current release tag. #1904

[Master] - 2026/02/05

Changed

• MINOR Added checks for unsupported multiphysics combinations. Cahn-Hilliard with heat transfer and Cahn-Hilliard with thermal buoyancy force now throw since these combinations are not currently supported. Using the isothermal ideal gas density model with the thermal buoyancy force now throws since the isothermal ideal gas model assumes thermal independence of the density, which is incompatible with the thermal buoyancy force. #1899

• MINOR Renamed buoyancy force to thermal buoyancy force in the multiphysics subsection to distinguish it from the Archimedes buoyancy force used in DEM/CFD-DEM. The parameter set buoyancy force is now set thermal buoyancy force, the assembler classes BuoyancyAssembly and BuoyancyAssemblyVOF are now ThermalBuoyancyAssembly and ThermalBuoyancyAssemblyVOF, and the matrix-free operator member buoyancy_term is now thermal_buoyancy_term. A deprecated alias ensures that existing parameter files using set buoyancy force continue to work. All affected tests, examples, and documentation have been updated. #1898

Fixed

• MAJOR This PR fixes the Boussinesq buoyancy term that was miscalculated in VOF. Contrary to the Navier-Stokes equations from the PSPGSUPGNavierStokesAssemblerCore, when using VOF, the density term appears explicitely in both left and right had sides of the assembly from GLSNavierStokesVOFAssemblerCore. As such, the BuoyancyAssembler from the base Navier-Stokes code did not compute the proper buoyancy term. This was fixed by adding a new buoyancy assembler specific for VOF navier_stokes_vof_assemblers and changed the setup assembler in both fluid_dynamic_matrix_based and fluid_dynamic_block to compute buoyancy properly. All tests affected by this change have been updated and a new VOF specific buoyancy test has been added to the application test suite. #1896

[Master] - 2026/01/29

Changed

• MAJOR This PR refactors adaptive time-step parameters. As pointed out in the review of PR #1886, having adapt controlling the time step with both the CFL condition and the capillary time-step constraint (with respect capillary time-step constraint enabled) seems inappropriate. Instead, both conditions can now be enabled independently. adapt time step to respect CFL can be set to true to control adaptive time-stepping with the user-chosen max cfl and adapt time step to respect CTR can be set to true to control the time step with max capillary time-step ratio. When both are enabled, the most constraining (smallest) sets the new time-step value. As this is an important parameter change, an alias was made for the old parameter adapt (=adapt time step to respect CFL).
  respect capillary time-step constraint has been replaced by adapt time step to respect CTR and capillary time-step ratio by max capillary time-step ratio.
  All tests and examples affected by this change have been updated.
  Additionally, all uses of "time-step" that are not as a compound adjective have been replaced with "time step". #1894

[Master] - 2026/01/27

Fixed

• MINOR Added a missing term in the matrix-free volume-filtered momentum conservation equation stress tensor. The term $\varepsilon_{\mathrm{f}} \nu \partial_j \partial_i u_j$ was omitted in the previous implementation. The outputs of the lethe-fluid-vans-matrix-free and lethe-fluid-particles-matrix-free application tests changed only slightly, except for MMS test case 2, which was updated so that the source term accounts for this correction. The outputs of the affected tests were updated accordingly. Essentially, this PR adopts the changes of #1890 into the matrix-free solver. #1895

[Master] - 2026/01/27

Changed

• MINOR The analytical Jacobian computation in the SignedDistanceSolver involves symmetric matrices and the implementation was not taking advantage of that. Additionally, intermediary matrices where reallocated each time the function was called. This PR improves the performance of compute_analytical_jacobian() by using the symmetry property in matrix-matrix products. It also includes the intermediary matrices as attributes of the SignedDistanceSolver class to avoid multiple re-instantiation. The gain in terms of computational time is about 20% in 3D. #1893

Fixed

• MINOR Added a missing term in the volume-filtered momentum conservation equation stress tensor. The term $\varepsilon_{\mathrm{f}} \nu \partial_j \partial_i u_j$ was omitted in the previous implementation. The outputs of the lethe-fluid-particles and lethe-fluid-vans application tests changed only slightly, except for MMS test case 2, which was updated so that the source term accounts for this correction. The outputs of the affected tests were updated accordingly. #1890

[Master] - 2026/01/26

Added

• MINOR This PR adds the option to set a simulation initial time-step that respects the capillary time-step constraint through enabling (setting to true) the parameter respect capillary time-step constraint ($\Delta t_\sigma$) in the simulation control subsection. This constraint is especially useful when simulating capillary flows. With the parameter capillary time-step ratio ($N_\text{CTR}$), users can specify a multiple of the default capillary time-step constraint as defined by [1]. By default, the $N_\text{CTR}$ is set to 1. A $N_\text{CTR}$ value < 1 can improve stability for highly dynamic cases, and using a $N_\text{CTR}$ value > 1 can lead to a significant decrease in computation time in some cases.

  Additionally, when respect capillary time-step constraint is paired with adapt (for adaptive time-stepping), the time-step will be dynamically updated to respect the capillary time-step ($N_\text{CTR} \times \Delta t_\sigma $) at every time-step. A warning message is printed on the console when adapt is disabled to inform the user that the capillary time-step constraint might not be respected if either of the mesh cell size, the densities or the surface tension coefficient evolves dynamically.

  Finally, a new overload of the announce_string function has also been added to allow multiple line banners. #1886

  [1] F. Denner, F. Evrard, and B. van Wachem “Breaching the capillary
  time-step constraint using a coupled VOF method with implicit surface tension,” J. Comput. Phys., vol. 459, p. 111128, Jun. 2022, doi: 10.1016/j.jcp.2022.111128

• MINOR This PR is a follow-up for the time harmonic electromagnetic auxiliary physics rudimentary implementation #1852. It links its physical material properties #1862 to the assembly, creates the waveguide port boundary conditions, update previous application tests related to the physics and add a new one for a dissipative medium. It also removes .prm in the examples/multiphysics/waveguide as this example will come in a follow up PR. #1882

[Master] - 2026-01-22

Fixed

• MINOR The hopper example post-processing script was not working anymore since the change in the definition of the floating wall. The script would try to parse "nx" from the .prm file, but this variable did not exist anymore. This PR fixes this issue by removing this parameter parsing. Furthermore, we have identified an issue with the automatic validation script which can keep on reusing old pdf of the results if the generation of the new ones did not work. This is also fixed by automatically removing all PDF that were already present in the case folder. #1889

[Master] - 2026-01-21

Changed

• MINOR The cylindrical gas–solid fluidized bed example, introduced in PR [#1844], has been added to the Lucille validation test suite. The selected validation case uses the matrix-free solver with a semi-implicit drag scheme and a QCM filter. The corresponding post-processing Python script has been modified to allow users to select the simulation configuration to be post-processed. #1880

Fixed

• MINOR Calls to convert_vector_dealii_to_trilinos() were failling due to new restriction on ghosted Trilinos vectors in dealii. This PR fixes this using a temporary locally owned vector. #1888

[Master] - 2026-01-20

Changed

• MINOR This PR improves the performances of the signed distance solver. Previously, the bottleneck was the calls to FEPointEvaluation.reinit(cell, points_vector) in compute_second_neighbors(). Hence, the cost of these calls has been reduce in two ways: 1) the numerical jacobian of the minimization problem was replace by the analytic jacaobian to reduce the number of points to reinit for and 2) the MappingFE(Fe_Q) was replaced by a MappingQ(fe.degree) to take the fast path in FEPointEvaluation.reinit() (those two mapping are equivalent, but MappingFe was not recognized for the fast path). For the 3D simulation of the rising bubble benchmark, we have a speed up of approx. 7x for the signed distance computations. Hence, the geometric reinitialization is not the bottleneck of the simulation anymore. #1885

[Master] - 2026-01-19

Changed

• MINOR The latest Lethe release is compatible with deal.ii 9.7, and we don't have CI checks with 9.6 version (or below) anymore. Hence, this PR removes deprecated checks for deal.II versions prior to 9.7. #1884

[Master] - 2026-01-16

Changed

• MINOR In the cylindrical packed bed example, the pressure drop across the bed is compared with the Ergun correlation. This was done in PR [#1840], where a bed porosity of 0.45 was used in the correlation. In this PR, the bed porosity is calculated using the bed height that is extracted from the simulation instead, leading to a better estimate for the pressure drop. [#1881] (#1881)

• MINOR This PR adds the option to declare a particle size distribution in the parameter file as volume-based for the normal and lognormal distribution. The custom distribution is the only distribution that is not supporting the number-based distribution. The will get fixed in a follow up PR. #1875

[Master] - 2026/01/15

Changed

• MAJOR The algebraic reinitialization PDE had some issues converging towards steady-state. To solve them, this PR:

  • changes the weak formulation of the problem solved (the curvature field is no more required);
  • changes how the artificial time-step is computed;
  • changes how the steady-state criterion is evaluated;
  • removes the filtered VOF solution field for the computation of the projected phase gradient used to compute the unit interface normal vector and the curvature;
  • renames the reinitialization CFL parameter to artificial time-step factor (an alias was made for reinitialization CFL, to avoid parameter file version issues), and;
  • changes default values of algebraic reinitialization parameters.

  This PR also updates the rising bubble example. Other VOF examples with surface tension force (static bubble, capillary wave, and Rayleigh-Plateau instability) will have to be checked and updated in a future PR. #1879

[Master] - 2026-01-13

Changed

• MINOR This PR replaces the duplicate set_insertion_type function definitions in dem.cc, cfd_dem_coupling.cc, and cfd_dem_coupling_matrix_free.cc with a single definition in set_insertion_method.cc. #1877

[Master] - 2026/01/12

Fixed

• MINOR The lethe-particles/distribution_normal.prm application test was using a log-normal distribution. The parameter was changed back to normal. As a result, the output of the test did change. #1876

• MINOR The convection term in the VANS equations for models A and B is changed from local_matrix_ij += ((phi_u_j * void_fraction * velocity_gradient * phi_u_i) + (grad_phi_u_j * void_fraction * velocity * phi_u_i)); to local_matrix_ij += ((velocity_gradient * phi_u_j * void_fraction * phi_u_i) + (grad_phi_u_j * void_fraction * velocity * phi_u_i)) in the matrix assembly, to match the correct algebraic formula. The output of the lethe-fluid-particles and lethe-fluid-vans application tests changed only slightly. Therefore, their outputs were updated in this PR as well. #1874

[Master] - 2026/01/07

Added

• MINOR The particle projector can be used to project the particle-fluid force onto the CFD mesh. This requires the assembly of a matrix and a right-hand side. On smaller meshes, this assembly is quite cheap, but when using the matrix-free methods, it becomes a significant cost for large parallel simulations. This PR optimizes this projection step by ensuring that the matrix and the preconditioner are only recalculated and reinitialized when it is necessary. In the case when the projected field does not have a Neumann boundary condition, then the matrix is only assembled once, whenever the degrees of freedom are set up, instead of at every iteration. This greatly diminishes the cost of the explicit, semi-implicit and implicit coupling. There are still optimizations remaining (for example, to carry out all the projections in a single step instead of one by one), but these will be addressed in a follow-up PR. This already reduces the cost by 20-25% of the projection. Furthermore, the projection was not adequately timed, this has been fixed in this PR. #1873

Fixed

• MINOR The use of an automatic pointer was creating a compilation error on modern C++ compiler. The communicator is explicitely declared instead of using an automatic pointer. This does not affect anything, but makes compilation more stable accross platforms. #1872

[Master] - 2026/01/06

Fixed

• MINOR The test read_mortar_data_02 constantly fails in the CI release, even if it passes on debug mode and also in local office computers. Since read_mortar_data_01 and read_mortar_data_03 are very similar to such test (only with different grids), this PR solves this issue by removing the (unnecessary) read_mortar_data_02 test. #1871

[Master] - 2025/12/19

Added

• MAJOR This PR adds a rudimentary version of the new time harmonic electromagnetic auxiliary physics solver. It puts in place the time_harmonic_maxwell.h and .cc files with the minimum required functions to solve the DPG linear system with two .prm files as input. The electromagnetic multiphysics, its most basic boundary conditions, the initial condition, the analytical solution, and the post processing of the interior fields function skeletons are set in place. The other functionality implementation will come in future PRs. The solver is tested with two new application tests based on the .prm. #1852

[Master] - 2025/12/23

Added

• MINOR This PR adds a gas-solid cylindrical fluidized bed example to the Lethe example suite. Different filtering and drag coupling approaches are compared using a robust benchmark problem: the dependence of the pressure drop on the superficial gas inlet velocity. VANS Model A is used with both QCM and cell-based filters using the matrix-based solver. The same model is also tested with the QCM filter using the matrix-free solver. For each configuration, three drag coupling strategies are considered: explicit, semi-implicit, and implicit. #1844

• MAJOR The unresolved CFD-DEM matrix-free implementation could not allow dynamic load balancing during the simulation since this feature had not been implemented yet. This adds the load balance implementation as well as make sure that it works well in both releaseand debug mode. An application test which is the sedimentation of a particle in parallel with dynamic load balancing is added to ensure that the test is stable in parallel since it was quite difficult to figure out all of the ghost logic of the vectors considering that both Trilinos and deal.II vectors are used in the ParticleProjector class. #1869

[Master] - 2025/12/19

Fixed

• MINOR This is the follow-up to PR 1855, where we fixed the infinite while loop related to solid surface. This PR adds an application that was falling previously to this fix. This PR also changes how the main loop on every solid object is built during the force calculation which results in a significant speed-up of the code. #1865

[Master] - 2025/12/18**

Fixed

• MINOR This PR fixes boundary list that were added in #1697. Boundary lists were not being parsed properly for physics other than fluid dynamic. The parameter parsing now expected a list of integers instead of an integer. #1866

[Master] - 2025/12/17

Changed

• MAJOR Floating walls declaration in a parameter file got changed so that it requires fewer parameters for the point on wall and the normal vector. A bug was also find during this change: the normal vector wasn't normalized after being parsed. As a results, if the user did not declare a unit vector in the parameter file, the normal overlap between particles and this floating wall is off by some factor. This problem got fixed, but resulted in the change of an application-test output (which was declaring the normal vector as a non-unit vector). #1850

• MINOR The verification of the number of cells at the stator and rotor interfaces was being done inside the loops for dealii and gmsh grids. This PR adjusts this by doing the verification only once, after the initial mesh refinement is performed. #1854

Fixed

• MINOR This is a follow-up of #1863. Although #1863 fixed the restart and prevented the simulations from crashing, the time history of the void fraction was not store appropriately. This stemmed from a confusion since in the matrix-free solver, it is the deal.II distributed vectors for the void fraction which are checkpointed and not the Trilinos ones. This PR reads the correct deal.II vector when reading a checkpoint, but also ensures that the values in the Trilinos vectors matches that of the deal.II vectors. This allows reproducing the norm of the residuals to machine accuracy when restarting. #1864

• MINOR The Matrix-free CFD-DEM solver could not restart adequately. This is because the solution vector for the fluid was not sized accordingly. The deal.II vectors require that the locally relevant dofs be provided to the vector before reading a checkpoint, which is not the case for the Trilinos vectors. This would prevent restarts in parallel. #1863

[Master] - 2025/12/16

Added

• MINOR This PR add the material properties that will be used by the time-harmonic electromagnetic solver which include the electric conductivity, the complex electric permittivity and the complex magnetic permeability. At the moment, those properties only support a "constant" field. A unit test for the electromagnetic constant properties was added, along with the update of the already existing "physical_properties_manager" tests. #1862

[Master] - 2025/12/15

Fixed

• MINOR The tolerance adopted in the radius computation at the rotor-stator mortar interface was a hard-coded value, which was not ideal. This PR fixes this by introducing a radius tolerance parameter. #1853

[Master] - 2025/12/14

Changed

• MAJOR A new message is added at the start of every DEM and unresolved CDF-DEM simulation which informs the user about the kind of distribution being used for every particle type. When using a normal or lognormal distribution, an extra message is written about the diameter cutoff values relative to the entire distribution. This change is MAJOR since every application test using the lethe-particles, lethe-fluid-particles and lethe-fluid-particles-matrix-free solver had to be updated. Also in this PR, the documentation relative to the update-golden.tl script got updated. #1849

Added

• MINOR This PR adds the possibility to use the semi-implicit and implicit drag couplings with the CFD-DEM matrix-based solver while also using the QCM filter to project the particle forces onto the fluid. At this stage, it has been tested with the single particle sedimentation case. #1845

[Master] - 2025/12/13

Fixed

• MAJOR The new implementation of the solid-particle contact detection could lead to an infinite loop for one of the cases that happens only on deformed mesh. The issue was that two continue statement could be called without having the iterator increased. This lead to the aforementioned bug. Running any example with a solid object (bunny drill or granular mixer) would directly lead to this infinite loop being encountered no matter the number of cores. The solution is simple (increment the iterator), but it also demonstrates that we need more robust testing for this part of the code. #1855

[Master] - 2025/12/11

Fixed

• MINOR The documentation for the simulation control and the analytical solution was improved. #1843

Removed

• MAJOR Officially deprecate the RPT applications and remove them. The applications are now available at https://github.com/chaos-polymtl/lethe-rpt. This significantly decreases the size of the repository and the length of the CI procedure. #1851

[Master] - 2025/12/10

Added

• MINOR This PR adds the possibility to change the diffusion factor of the VOF DCDD stabilization in the prm file. #1847

Fixed

• MINOR The extract-slice-from-vtu.py tool was not working properly with --np > 1 because an argument (file path) was missing in the call of extract_slice. This PR fixes this bug and add 2 functionalities. 1) When the flag group files in the .prm (parallel output of Lethe) was set to a value larger than 1, the extract-slice-from-vtu.py would not slice all .vtus associated with a .pvtu. Since pyvista can read .pvtus correctly, the list of files to read is now based on .pvtus instead of .vtus. 2) There was no sliced .pvd file generated, so the slices could not be used easily in other post-processing tools using .pvds. The .pvd file of the slices is now generated. #1848

Full Changelog: v1.0.3...v1.0.4