Skip to content

Release candidate 2 for 2.2

Pre-release
Pre-release

Choose a tag to compare

View all tags
@RemDelaporteMathurin RemDelaporteMathurin released this 03 Sep 20:54
· 44 commits to main since this release
v2.2-rc.2
9961e80
This commit was created on GitHub.com and signed with GitHub’s verified signature.
GPG key ID: B5690EEEBB952194
Verified
Learn about vigilant mode.

FESTIM v2.2-rc.2

Second release candidate for 2.2. The headline of this one is codimensional (manifold) subdomains — transport along a grain boundary, a crack or a thin surface layer, coupled to the bulk — and drift terms, which bring back Soret from FESTIM 1 and add electromigration. Alongside those, reactions have been reworked into a proper class hierarchy, field exports gained new formats (including single-file vtkhdf), and a series of fixes to the discontinuous/Nitsche interface machinery.

Please try it out and report anything that breaks before 2.2 final.

pip install festim==2.2rc2

What's Changed

Major

Codimensional (manifold) subdomains 🎉

A VolumeSubdomain can now be a manifold embedded in the mesh — a line in a 2D mesh, a surface in a 3D mesh — carrying its own transport equation and exchanging with every bulk subdomain it touches. This is how you model a grain boundary, a crack, or a thin surface layer without resolving it with cells. See the new Subdomains user guide.

gamma = F.VolumeSubdomain(
    id=2, material=mat, dim=1, locator=lambda x: np.isclose(x[1], 0.5)
)

Derived quantities (SurfaceFlux, TotalSurface, AverageSurface, TotalVolume, AverageVolume) now work on a manifold, on its own boundary, and for a bulk species across an interior manifold — the last of which used to silently report 0.0. And a manifold may now be linked to any number of adjacent volumes, not just two, so a grain-boundary network can thread a polycrystal where each grain is its own subdomain.

Drift terms

Transport driven by a gradient other than the species' own, all sharing one conservative div(c v) assembly:

term drift velocity driving field
F.AdvectionTerm (existing) given directly a moving fluid
F.SoretTerm -D Q*/(k_B T²) grad(T) temperature
F.ElectromigrationTerm -z D/(k_B T) grad(phi) electric potential 
model.drift_terms = [
    F.SoretTerm(species=H, Q_star=0.2, subdomain=vol),
    F.ElectromigrationTerm(species=OD, charge=1, potential=phi, subdomain=membrane),
]
model.boundary_conditions = [F.OutflowBC(subdomain=outlet, species=H)]

Soret was documented in the theory guide but had no implementation in FESTIM 2 — this closes that v1 → v2 regression. Also here: the new F.OutflowBC, and SurfaceFlux now reports the total flux -D grad(c)·n + c v·n (the "advection terms are not accounted for" warning is gone).

Reaction re-work

Reaction becomes a small hierarchy so FESTIM can express reactions beyond Arrhenius trapping/detrapping, and reactions are now expanded into ParticleSource objects rather than written into the formulation by each problem class.

class net rate
ReactionBase arbitrary R = f(c_i, x, T, t)
GenericReaction mass action
ArrheniusReaction k_0/E_k, p_0/E_p (the old Reaction)
DecayReaction first-order radioactive decay

Rate coefficients are now festim.Value objects, so they accept floats, UFL expressions, fem.Constant/fem.Function, or callables of T, t, x and other species.

New export formats

Field exports are no longer VTX-only. The format is now an argument, backed by a FieldWriter strategy, and adding a format is one small class.

format extension ParaView
"vtx" .bp yes (default, unchanged)
"vtkhdf" .vtkhdf yes — new, one HDF5 file instead of a directory tree
"xdmf" .xdmf yes
"checkpoint" .bp / .h5 no — now available for all field types 
F.SpeciesExport("results.vtkhdf", field=[H], subdomain=vol, format="vtkhdf")

Exports pointing at the same .vtkhdf filename become named blocks of a single MultiBlockDataSet, so a multi-material model no longer scatters one .bp directory per subdomain.

Fixes

Worth calling out #1238: interface.method was dead — every interface's method was overwritten with the class default on every run, so only the deprecated problem-level route worked. On top of that, nitsche_method left D out of its consistency term, ignored the solubility-law branching that penalty_method has, and applied penalty_term to a quantity in potential rather than flux units. With realistic data that last one put Nitsche out by 4× at penalty_term = 10 and 280× at 1e3. The constraint is now built once in Interface.equality() and shared by both methods. penalty_method is behaviourally unchanged.

#1239 fixes meshtags definitions to include ghost cells, plus a logger bug — both needed for correct parallel runs.

Docs

New pages: Drift terms, a rewritten Subdomains page covering manifolds, and an expanded Exports & post-processing page.

Misc / CI

Deprecations and breaking changes

old new
F.Reaction F.ArrheniusReaction (alias kept, warns)
F.VTXSpeciesExport / F.VTXTemperatureExport F.SpeciesExport / F.TemperatureExport with format="vtx" (aliases kept, warn)
F.XDMFExport F.SpeciesExport(..., format="xdmf") (alias kept, warns)
VTXSpeciesExport(..., checkpoint=True) format="checkpoint" (mapped, warns)
model.advection_terms model.drift_terms (appended, warns)
problem.method_interface interface.method

Removed outright:

  • F.ExportBaseClass → F.FieldExportBase.
  • The festim.exports.vtx module → festim.exports.field.

Behaviour changes to be aware of:

  • SurfaceFlux now includes the drift/advection contribution, so reported values change for any model with an advection term.
  • interface.method is now actually honoured — a discontinuous model that set it and silently got the class default will now solve with the method it asked for.

Full Changelog: v2.2-rc.1...v2.2-rc.2

Contributors

dependabot, RemDelaporteMathurin, and 2 other contributors
Assets 2
Loading