feat: add PermeabilitySpecification as an high-level FieldSpecification by kdrienCG · Pull Request #4019 · GEOS-DEV/GEOS

kdrienCG · 2026-04-07T07:59:21Z

(Previously #4012)

This PR proposes to add an easy way to add higher-level components that create FieldSpecifications without the boilerplate.

As an example, to define the permeability you have to specify 3 differents FieldSpecifications.
One for the x-axis, a second for the y-axis, and a last one for the z-axis.
There is also some implementation details that could be hidden, like the component XML attribute for example.

<FieldSpecifications>
  <FieldSpecification
      name="permx"
      component="0"
      initialCondition="1"
      setNames="{ all }"
      objectPath="ElementRegions/reservoir"
      fieldName="rockPerm_permeability"
      functionName="permxFunc"
      scale="9.869233e-16"/>

  <FieldSpecification
      name="permy"
      component="1"
      initialCondition="1"
      setNames="{ all }"
      objectPath="ElementRegions/reservoir"
      fieldName="rockPerm_permeability"
      functionName="permyFunc"
      scale="9.869233e-16"/>

  <FieldSpecification
      name="permz"
      component="2"
      initialCondition="1"
      setNames="{ all }"
      objectPath="ElementRegions/reservoir"
      fieldName="rockPerm_permeability"
      functionName="permzFunc"
      scale="9.869233e-16"/>
</FieldSpecifications>

With this PR, their would be a PermeabilitySpecification component that would create behind the scene those three FieldSpecifications to keep full compatibility with other parts that rely on FieldSpecificationBase. One could think of PermeabilitySpecification as a blueprint or recipe to create FieldSpecificationBase objects.

Here is how it looks like for PermeabilitySpecification:

<FieldSpecifications>
    <PermeabilitySpecification
      name="perm"
      setNames="{ all }"
      regionNames="{ reservoir }"
      fieldName="rockPerm_permeability"
      functionName="permFunc"
      scales="{9.869233e-16, 9.869233e-16, 9.869233e-16}"/>
</FieldSpecifications>

The following architecture is proposed:

This way, similar components could be added by providing a data class (like PermeabilitySpecification) and a factory with a generate method to describe how to transform the high-level components into one or multiple "low-level" FieldSpecificationBase.

Implement methods to add factories to the manager to handle the creation of FieldSpecificationBase object via higher-level specifications (like PermeabilitySpecification)

rrsettgast · 2026-04-07T20:35:22Z

Hi @kdrienCG
This is something we have been meaning to get to for a while. But not just for perm. Can you implement a generalization to allow for processing and application of arbitrary tensor inputs? There are many things that this would be useful for besides permeability. I think we could read in a "scale" as any array type, and apply appropriately. Then this could be used for stresses, displacements, or any other non-scalar field without multiple FieldSpecificaiton blocks.

kdrienCG · 2026-04-10T08:01:50Z

Hi @kdrienCG This is something we have been meaning to get to for a while. But not just for perm. Can you implement a generalization to allow for processing and application of arbitrary tensor inputs? There are many things that this would be useful for besides permeability. I think we could read in a "scale" as any array type, and apply appropriately. Then this could be used for stresses, displacements, or any other non-scalar field without multiple FieldSpecificaiton blocks.

Hi @rrsettgast , and thanks for the suggestion
I agree there should be a generalized way to do this, beyond permeability.

I propose doing that in a follow-up PR so we can keep this one focused on specialized components and easier to review.

I've also put together a prototype to test the generalized approach, I can open a separate PR so we can agree on what its interface should be.

Modify the specification parameter name in PermeabilitySpecificationFactory to match the parent class method definition (FieldSpecificationFactory)

rrsettgast · 2026-04-17T08:38:35Z

@kdrienCG I would really insist that don't create a dedicated FieldSpecification for permeability. This should be handled in the generic way, with an improvement on the processing of "scale" to allow for tensor input, and the subsequent processing.

MelReyCG · 2026-04-17T15:11:33Z

Hi @rrsettgast, the goal here was to offer a user-oriented interface, as FieldSpecification is more developper oriented with no real interface between user configuration and internal GEOS data.

objectPath gives access to all the mesh data repository, what one can use for a given field is not documented, and per-field validation would be tricky to integrate directly in it (moreover, the data-hierarchy is coupled with all user inputs),
fieldName exposes data that could be considered as internal for most users, and if a user does not dive into all GEOS example, no clear list of them really exists anywhere (if you don't open all the fields headers, which are developper oriented).

I understand that this very proposal of the idea of specialized user-oriented components for each common field can seem quite empty for now, as there is no validation for the field for now, but it offer an opportunity to add specialized validations, dedicated documentation and a stable interface.
Maybe it is not the best approach, or maybe this component is not the best example, but we would like to give it a try. At term more components would be added, for high-level user configuration usecases.

Adding a vectorized version of the FieldSpecification is something we planned to do anyway, I'll be away for one month, in the meantime, @kdrienCG can prioritize the development of the vectorized FieldSpecification, which would then base this PR on.

MelReyCG · 2026-04-17T15:28:52Z

Also, we don't have region name array on FieldSpecification, it is also an improvement that this PR brings. We also could add that on the FieldSpecification.

MelReyCG · 2026-04-17T08:25:44Z


   AquiferBoundaryCondition
+
+   PermeabilitySpecification


Hmm.. I don't see that in the generated readthedocs build.

maybe its an issue due to the aborting of the jobs on the last CI compilation

MelReyCG · 2026-04-17T08:29:56Z

+     <PermeabilitySpecification
+       name="perm"
+       setNames="{ all }"
+       regionNames="{ reservoir/block1 }"


Can we do that?

Suggested change

regionNames="{ reservoir/block1 }"

regionNames="{ reservoir }"

And what about that to target all region? (maybe you'd have to implement something on * in the factory)

Suggested change

regionNames="{ reservoir/block1 }"

regionNames="{ * }"

Maybe we should these syntaxes in the examples.

MelReyCG · 2026-04-17T08:31:57Z

+**PermeabilitySpecification** is an optional, higher-level XML tag that you can place in the **FieldSpecifications** block. 
+It describes a 3-axis permeability on one or more element regions.


Suggested change

**PermeabilitySpecification** is an optional, higher-level XML tag that you can place in the **FieldSpecifications** block.

It describes a 3-axis permeability on one or more element regions.

**PermeabilitySpecification** is a XML tag that you can place in the **FieldSpecifications** block to describe a 3-axis permeability on one or more element regions.

It is an higher-level component than **FieldSpecification**, specialized on permeability.

MelReyCG · 2026-04-17T08:50:40Z

+  void setComponent( int component )
+  {
+    m_component = component;
+  }


1 liners (only the methods you added, as you did the rest in another PR)

MelReyCG · 2026-04-17T08:52:06Z

+public:
+
+  /**
+   * @defgroup alias and functions to defined statically initialized catalog


Suggested change

* @defgroup alias and functions to defined statically initialized catalog

* @defgroup alias and functions to define statically initialized catalog

MelReyCG · 2026-04-17T13:56:43Z

+
+  R1Tensor scales = ps->getScales();
+
+  for( string const & regionName : ps->getRegionNames() )


Is it possible to add a validation of the region names?

MelReyCG · 2026-04-17T15:22:22Z

+
+  stdArray< string, 3 > suffixes = {{ "_x", "_y", "_z" }};
+
+  R1Tensor scales = ps->getScales();


We would need to GEOS_ERROR() on negative values.

rrsettgast · 2026-04-17T19:16:07Z

Hi @rrsettgast, the goal here was to offer a user-oriented interface, as FieldSpecification is more developper oriented with no real interface between user configuration and internal GEOS data.

I don't understand what exactly is meant when you say that FieldSpecification has "no real interface between user configuration and internal GEOS data. It is the specification of "field data". I read it as an implication that a "user" will not understand the concept that permeability is stored as a field. This is pretty basic.

objectPath gives access to all the mesh data repository, what one can use for a given field is not documented, and per-field validation would be tricky to integrate directly in it (moreover, the data-hierarchy is coupled with all user inputs),

This seems like it is a documentation issue.

I do not understand what you mean by "per-field validation". Do you mean checking that the specification makes sense? The criteria for this check is not determined at the specification action level.

The coupling of data with user inputs is intentional.

fieldName exposes data that could be considered as internal for most users, and if a user does not dive into all GEOS example, no clear list of them really exists anywhere (if you don't open all the fields headers, which are developper oriented).

This is a documentation issue. How will the user know they can use a "PermeabilitySpecification" block, and what the available attributes/inputs are for that block? I guess they would have to find the specification somewhere in the documentation or examples? Is this any harder than finding the examples with "FieldSpecification" setting the permeability field?

Also, lucky for us that claude or codex/ChatGPT can easily figure this stuff out now. Just give the agent access to the examples and documentation and it will do it for you.

I understand that this very proposal of the idea of specialized user-oriented components for each common field can seem quite empty for now, as there is no validation for the field for now, but it offer an opportunity to add specialized validations, dedicated documentation and a stable interface. Maybe it is not the best approach, or maybe this component is not the best example, but we would like to give it a try. At term more components would be added, for high-level user configuration usecases.

Can you give examples of the type of validation that must occur specifying a field? Why must it be a stand alone class in field specification rather than validation based on field name and specified solvers? I think it is correct to say that the solvers should be the ones decided what input specifications are valid not the actual FieldSpecification, and a mechanism exist for this already. Do the "Initialization" functions from Group not do this?

Adding a vectorized version of the FieldSpecification is something we planned to do anyway, I'll be away for one month, in the meantime, @kdrienCG can prioritize the development of the vectorized FieldSpecification, which would then base this PR on.

This really would solve a lot of "user interface" issues. However again, claude and codex handle the replication for you without any error.

kdrienCG added 6 commits March 27, 2026 09:59

add FieldSpecificationABC abstract class

0c79a66

Move FieldSpecificationBase catalog to FieldSpecificationABC

f234750

add PermeabilitySpecification

cf11e8f

add FieldSpecificationFactory interface

35d9a46

Add PermeabilitySpecificationFactory

a5ddb58

Add specifications factory creation logic to FieldSpecificationManager

7098e09

Implement methods to add factories to the manager to handle the creation of FieldSpecificationBase object via higher-level specifications (like PermeabilitySpecification)

kdrienCG self-assigned this Apr 7, 2026

kdrienCG added type: feature New feature or request type: new A new issue has been created and requires attention labels Apr 7, 2026

kdrienCG mentioned this pull request Apr 7, 2026

feat: add PermeabilitySpecification as an high-level FieldSpecification #4012

Closed

kdrienCG added 2 commits April 7, 2026 17:44

set description for scales wrapper

dca1b4a

change type of m_scales to R1Tensor

1efaccf

kdrienCG added 2 commits April 8, 2026 09:28

modify for loop type to integer

e40b8c9

add RST documentation for PermeabilitySpecification

c736a7d

kdrienCG added 2 commits April 10, 2026 15:06

uncrustify

42f7c62

Merge branch 'develop' into feature/kdrienCG/permeabilitySpecification

7a2d7e8

kdrienCG added ci: run CUDA builds Allows to triggers (costly) CUDA jobs ci: run integrated tests Allows to run the integrated tests in GEOS CI labels Apr 13, 2026

kdrienCG marked this pull request as ready for review April 13, 2026 08:48

kdrienCG requested review from MelReyCG, OmarDuran, corbett5, cssherman and rrsettgast as code owners April 13, 2026 08:48

kdrienCG added the flag: no rebaseline Does not require rebaseline label Apr 14, 2026

kdrienCG added 2 commits April 14, 2026 14:03

add missing documentation

16f7e43

fix parameter name

74cda9c

Modify the specification parameter name in PermeabilitySpecificationFactory to match the parent class method definition (FieldSpecificationFactory)

kdrienCG removed the ci: run CUDA builds Allows to triggers (costly) CUDA jobs label Apr 14, 2026

MelReyCG reviewed Apr 17, 2026

View reviewed changes

	regionNames="{ reservoir/block1 }"
	regionNames="{ reservoir }"

		PermeabilitySpecification is an optional, higher-level XML tag that you can place in the FieldSpecifications block.
		It describes a 3-axis permeability on one or more element regions.

	* @defgroup alias and functions to defined statically initialized catalog
	* @defgroup alias and functions to define statically initialized catalog


		R1Tensor scales = ps->getScales();

		for( string const & regionName : ps->getRegionNames() )


		stdArray< string, 3 > suffixes = {{ "_x", "_y", "_z" }};

		R1Tensor scales = ps->getScales();

Conversation

kdrienCG commented Apr 7, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

rrsettgast commented Apr 7, 2026

Uh oh!

kdrienCG commented Apr 10, 2026

Uh oh!

rrsettgast commented Apr 17, 2026

Uh oh!

MelReyCG commented Apr 17, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

MelReyCG commented Apr 17, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

rrsettgast commented Apr 17, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

kdrienCG commented Apr 7, 2026 •

edited

Loading

MelReyCG commented Apr 17, 2026 •

edited

Loading

rrsettgast commented Apr 17, 2026 •

edited

Loading