Note for now much of the docs is LLM written. This was done to save time and focus on code development. The docs have been LOOSLEY reviewed. However, the code itself has been either fully written by hand or fully reviewed. Therefore, the docs should at the moment be seen as a loose resource rather than authoratiative (and this is on top of the general ability for docs to drift)
Much of the code to do actual finite element computations lives in this backend. The idea here is that the physics is all seperate and more descriptive than the backend. Further, we could, in principal swap out to another finite element backend (e.g. deal.II) without messing up stuff outside of this backend. Note LLM's made signifigant contributions to this module
LLMs (ChatGPT6 astra max and Claude Opus 5.5 medium) made signifigant contributions to this module. All LLM written code has been read over and verified.
There are loads of things (solutions, models, solver descriptions, mesh's, etc..) which need to be exported from SERiF and then either reimported into SERiF or into some other program. This module is responsible for all of that. Generally with the goal of feeling like the fmt / new format module in C++23 and on (e.g. by specializing formatting structs)
Note that LLM's made signifigant contributions to this module (ChatGPT 6 astra max and Claude Opus 5.5 Medium). All code has been reviewd manually
The initial prototype for this code used a number of bespoke so-called "prepared" operators to avoid recomputation of values which we could be sure would not change. However, this system was hard to scale. Here we implement an equivalent, but much more scalable, solution through a computational graph which keeps track of inputs and outputs to each node and only reruns the node when the inputs have changed. Note that this is a simplistic optimization scheme, we are do not check for example if the outputs change strongly or even at all with different inputs (generally that would require derivatives of the outputs wrt. each input) nor do we do any sort of graph optimization.
the seed system has two jobs, get the lane-emden solution for a reasonable n and project that onto the mesh. Note that the seed system does not solve lane-emden, that is in utils/laneemden (so that it can be reused by other systems). Currently SERiF only solves polytrope so the lane-emden initial guess is generally very good; however, as we move to non polytropic EOS we will still use a projected lane-emden as our initial guess for the starting model
The system matrix for a problem may be poorly conditioned, preconditioners are supposed to efficiently estimate the inverse of the system matrix so that a simpler problem, with the approximate identity matrix may be solved instead. The problem is that the best approach to this varies with different fields. The preconditioner system implements infrastructure to define seperate preconditioners for different fields which are then composed together.
The dynamical range of different fields SERiF must solve for is massive. This just breaks any reasonable preconditioner / spreads the eigen modes of the system matrix out. This is a normalization system which uses charectaristic scale factors (e.g. the approximate radius estimated using the lane-emden equation) to rescale different fields to a more similar numeric scale. This turns out to be essential for stable convergence. Broadly this implements Riesz normalization along with exact diagnoal normalization.
This uses a linear solver from solver/linear which then calls some linear solver from the backend. Note that MFEM's build in newton solver is very simplistic and not sufficient for our needs; therefore we implement a more robust one here (and this is why newton is in the frontend and not the backend)
As with much of the code, the actual solvers are implemented (through MFEM) in the backend. This provides an interface so we can more easily swap out the linear solvers on the backend in the future
A representative example is angular momentum. It may be useful to not spin a model up all the way initially (due to convergence issues) rather the continuation system allows for a model to be spun up over a few solves so that it can more reliably reach a stable state
Operators defines how SERiF concepts map into MFEM (or generally any backend) concenpts and types. Since we are trying to seperate the specific MFEM implementation out of SERiF most of the code that was here has moved to backend. However, what remains is some general code related to the block layout of a systen and the contributions of different equations to different parts of that block layout
SERiF defines a so-called "model" subsystem. A model is a fully compile-time description of a problem. Note that this is a description not an evaluation tool. The basic idea is that since we have this robust description we can more easily serialize and be confident that others who load a model are getting the exact same thing. Further, this provides a convient place to do things like validate that all options are compatible, do some limited initial construction of the needed computational graph, allocate needed memory, etc... Some of the stuff that might initially seem to belong to a model will be in the discritization system though (e.g. FEM object lifetimes)
The mapping code is fundamentally backend dependent. Previously we had DomainMapper here; however, since it depende on MFEM we have moved it to the backend. The mapping module now just includes parts of the backend so that prior code will not break
The surface needs some defined condition (e.g. Isobaric) This module defines how the surface is defined. Again, much like the deformation system this does not actually implement much of the code to deform the surface to that condition; rather, it implements code to allow the prescription to be described robustly at compile time
The model must be able to deform to capture the shape induced by rotation or an external potential. Here we add the precription to descibe how we allow deformation. Note that the code to define how deformation is actually implemented is in the backend.
previously we modeled gravity as a mixed formulation. However, this turns out to not be needed with the improved surface prescription. Removing this and returning to a simpler gravity system dramatically reduces the number of unknowns and therefore speeds up the system.
