Enhancing AD system management: equations and DOFs

[vlipovac]

Hei alle sammen,

I would like to propose some modifications and enhancements to the existing DofManager and the ad.EquationManager.

The aim is to enable a dynamic way of creating DOFs and variables, and to reduce the amount of necessary code in the models to do so.

Disclaimer: I will make statements based on my current understanding/ overview of PorePy. If I am missing something or if something is simply wrong, please correct me. That might happen since I have a very limited overview on what the geomechanical models (for example) currently demand from the DofManager and the EquationManager.

This are the benefits:

1. It will be easier to create model classes which contain multiple physics ( I will demonstrate that in short time for compositional flow)
2. It will benefit future code maintenance simply by centralizing some functionality and removing code which is currently being repeated again and again in each model class and derived model classes.
3. It will benefit students and developers when they dive into PorePy for the first time. In my opinion newcomers have an extreme and overwhelming amount of things to learn before they can actually make models i.e., model equations for certain problems. And we can avoid having them deal with the data structures behind the mixed-dimensional grids, and the data structures behind the AD framework and its operators.

What are the changes:

There are no major changes to how models are currently created and how they use the DofManager and the ad.EquationManager. It is mostly a refactoring, with some minor new functionalities based on what I understand is the purpose of those two classes.

I have already implemented prototypes of all changes in the branch Composite Flow Extension

The modified DofManager
The new ADSystemManager

If this discussion bears fruit, the changes will be implemented in a separate branch and sent to a PR for review.

Changes to the DofManager

The modifications here are minor. Based on the present approach, DOFs can be appended to the block-dof data structure for given variable names (strings).

Additionally I have introduced porepy.SECONDARY_VARIABLES, which for now only changes where numpy arrays are stored in the data dictionary. Even if a variable is declared as secondary, it still contributes to the global DOF vector, as it is currently the convention (see how the current EquationManager assembles the system).
I am introducing this only to foreshadow some things, which are currently brewing, such that those changes only happen here in the background without demanding another refactoring processes of the models.

The current order of DOFs consists of multiple loops

1. Firstly, for all subdomains (outer loop), all declared primary variable DOFs (inner loop) are added, then all declared secondary variable DOFs (second inner loop) are added.
2. Secondly, for all interfaces (outer loop) all declared primary variable DOFs (inner loop) are added, then all declared secondary variable DOFs (second inner loop) are added.

So we have two successive outer loops, where each one has two successive inner loops. This happens at instantiation.

Now, if one wants to add DOFs after the instantiation, one has to append DOFs to the already existing DOFs. This ensures that the indices are chronologically preserved. The internal order of this new block of DOFs is the same as above.
See append_dofs and the private method _create_dofs, where the actual implementation is. This private method is currently the only method actually fixing the global order of DOFs. It is an extension of the code found in the constructor of the current DofManager.

Finally, a method to create a projection matrix to a subset of variables is added, which was originally a private method in the equation manager. I think this class is the correct place for that. The transpose of the projection can be used to slice the Jacobian (see the reworked assemble-X methods in the ADSystemManager).

Important: I have noticed that the DOF manager works independently of the AD framework and uses the variable name to identify variables and block DOFs. This is preserved and cemented as the formal way the DofManager works. I.e., DofManager methods operate on combinations of variable names and grids/ mortar grids.

The new ADSystemManager

The ADSystemManager aims to replace the EquationManager. The name is motivated by the fact that not only are the equations managed (rows) but also the variables (columns), which in the end is the whole system represented in the AD framework.

The essential rework is the variable management, especially the dynamic creation of the variables, see create_variable.
Ivar gave me an overview on how many wild and exotic combinations of DOFs and domains of definition are necessary for this method and I think I have constructed a signature which makes everything possible, without overburdening the user. The default-created variable is a variable which has a single value per cell in each subdomain. Everything else can be configured, i.e. DOF types added, specific subdomains and interfaces set as domains of definition.

I note at this point that the current implementation of PorePy supports only cell-wise DOFs on interfaces, as evident in the comments and implementation.

For variable management, this class has additional shallow wrappers to set and get variable values in local form, i.e., vectors which only contain the DOFs for respective variable. This will be useful in multi-physics problems.
For example in compositional flow, I am working with vectors of variable-specific size denoting various fractions, since the flash problem is decoupled from the flow problem.

Finally, all assemble-X methods the ad.EquationManager has, are also present in a reworked form, without changing the original signature. If you take a look at my proposed implementation, you will realize that the proposed refactoring eases the code significantly.

Other minor changes and comments

I have noticed that an atomic (single-domain) variable is basically identified by its name and the grid (or mortar grid) it is defined on.
Following that I have introduced read-only properties for the ad.Variable class, such that this information can be accessed and used for the management inside the ADSystemManager.

I have reworked all docstrings of above classes according to the current state of the convention, which we want for our docs.

What now

Please let me know what you think of the proposed changes. Testing is work in progress.
I am currently adapting my compositional flow model to the modified classes. As soon as I got that, I can demonstrate above usefulness directly on an example and we can extend the discussion.
I just want to point out again, that this is no major surgery on the way models operate right now. There is no equation factory or similar. But it paths the way to future modularization of the modelling process.

[vlipovac]

Enclosed is a minimal working example.
It demonstrates to which extent the declaration of variables and setting of values can be reduced when making a model class.

The setting of values can be used for e.g., setting of initial values or setting of values resulting from a separate calculation for a sub-problem.
dbg.txt

[keileg]

Thanks for the thorough summary @vlipovac. I will have a look at this over the coming days, however, I probably won't have time to fully digest this until next week.

@IvarStefansson, @OmarDuran: I would be very interested in hearing your opinions on this as well - I think it is potentially both very useful, but it could also set conditions for how other parts of the code will be formed, so we have to get it right.

I suggest we mainly do face-to-face discussions on this for now, if that make sense for everyone.

[vlipovac]

This has been resolved with the introduction of the EquationSystem