Expose mid-level functions to user

[BenjaminRodenberg]

The fenics-adapter offers a very high level interface. This allows to have minimal code changes in existing examples (see heat.py), but also limits the user. The following functions can wrap preCICE functionality, while allowing the user to access preCICE at a low level:

def read_block_scalar_data(self._read_data_id, mesh, V):
    precice.read_block_scalar_data(self._read_data_id, self._n_vertices, self._vertex_ids, self._read_data)
    # read_data -> CustomExpression
    return CustomExpression

def write_block_scalar_data(self._write_data_id, u):
    # u -> write_data
    precice.write_block_scalar_data(self._write_data_id, self._n_vertices, self._vertex_ids, self._write_data)

def set_mesh(mesh, SubDomain: coupling_boundary):
    precice.setMeshEdge(...)
    precice.setMeshVertices(...)

#preprocessing

mesh = UnitSquareMesh(10, 10)
m_f = MeshFunction(size_t, mesh, 1)
subdomain.mark(m_f, marker)

def set_mesh(mesh, int: marker, m_f):
    # mesh, marker, m_f ->  coupling_mesh_vertices, n_vertices
    precice.setMeshEdge(...)
    precice.setMeshVertices(...)

[BenjaminRodenberg]

A first example using the interface can be found in precice/tutorials@0eb3d81

[IshaanDesai]

Here is an outline of the design of the mid-level interface that is proposed:

# functions to help user have greater access to preCICE API via fenics-adapter
# Initialization 
def initialize( ... ):
    # Mostly similar to current "initialize" function in the adapter because further functions will
    # provide more control to the user

# Generic READ function
def read(self, quantity_name, mesh_name):
    # function will determine if given quantity is scalar or vector
    # function will extract all relevant vertex data like quantity_id, mesh_vertex_ids etc.
    read_data = precice.read_vector_data( ... ) /OR/ precice.read_scalar_data( ... )  /OR/
                        precice.read_block_vector_data( ... ) /OR/ precice.read_block_scalar_data( ... )
    return read_data

# Generic WRITE function
def write(self, quantity_name, mesh_name):
    # function will determine if given quantity is scalar or vector
    # function will extract all relevant vertex data like quantity_id, mesh_vertex_ids etc.
    precice.write_vector_data( ... ) /OR/ precice.write_scalar_data( ... ) /OR/
    precice.write_block_vector_data( ... ) /OR/ precice.write_block_scalar_data( ... )

def get_mesh_vertex_data(self, mesh_name):
    # Extract all relevant vertex data
    # Return multiple arrays with all interface mesh vertex related data
    return vertex_ids, vertex_positions, n_vertices, . . .

def get_mesh_edge_data(self, mesh_name):
    # Extract all relevant edge data
    # Return multiple arrays with all interface mesh edge data
    return edge_ids, edge_points_connections, n_edges, . . .   

def create_boundary_condition(mesh_name, boundary_condition_name):
    # Extract relevant mesh details
    # Apply boundary condition in FEniCS according to key word specified

def add_checkpoint(solver_state):
    # Add checkpoint at a place in the iteration loop

def restore_state(checkpoint):
    # Restore solver state to the provided checkpoint

• The user can provide FEniCS data directly and the functions defined above will convert the data to preCICE style.
• The user will still have access to the old def advance function which is currently implemented, giving the user the choice to have more freedom or less freedom to access the underlying API directly.

@BenjaminRueth and @ajaust could you please give inputs on this? Your inputs in the initial phases of this change would be very helpful!

[uekerman]

Overall, I think that this is a very good step. Some further thoughts:

• It could be dangerous to combine the old high-level API with the mid-level API. Ideally, both should be different classes.

from fenicsadapter import L1Adapter

• Why are

def get_mesh_vertex_data(self, mesh_name)
def get_mesh_edge_data(self, mesh_name)

needed?

• add_checkpoint -> save_checkpoint (there can only be one)

• What does create_boundary_condition exactly do? Is it a replacement for set_mesh?

• How does the configuration then work? Should this happen in the solver code or in the adapter? I guess in the solver code as mesh_name and quantity_name need to be known.

[IshaanDesai]

I agree that it will be wise to separate the high-level API and low-level API into separate classes.

My reasoning of providing:

def get_mesh_vertex_data(self, mesh_name)
def get_mesh_edge_data(self, mesh_name)

was that at some point the user would like to modify the mesh in a particular way or use the mesh data to modify particular scalar or vector values defined on the mesh. Does this go in the direction of a low-level API? In that case we can omit this for the mid-level API.

Currently set_coupling_mesh only defines and sets the interface mesh vertices and edges. create_boundary_condition will take user inputs in the form of Dirichlet or Neumann and the quantity name like forces, temperature or heat flux and set the boundary condition in FEniCS.

Right now the plan is to keep the configuration in the solver code.

[uekerman]

My reasoning of providing ... was that at some point the user would like to modify the mesh in a particular way or use the mesh data to modify particular scalar or vector values defined on the mesh.

I would recommend to only add this functionality once it is really needed. I currently don't see a use case for this. Am I missing sth?

Does this go in the direction of a low-level API?

In this context, with low-order, I would refer directly to the preCICE API. So, no.

create_boundary_condition will take user inputs in the form of Dirichlet or Neumann and the quantity name like forces, temperature or heat flux and set the boundary condition in FEniCS.

Is this related to the coupling? Is any preCICE functionality called there? Let's not take pure FEniCS functionality to the adapter if there is not a really good reason.

Overall, I think, we need to be careful to not over-engineer this mid-level API. Let's start low and add functionality whenever necessary.

Please have a look at the Nutils CHT example. We use no adapter here, but directly the preCICE API and end up at only 130 lines of code. Especially with the new Python API, directly using the preCICE API is also really readable. The mid-level adapter should encompass exactly that functionality that is technical and repetitive, but not those parts that actually help to understand how the coupling works. But I guess we already agree on this, just wanted to write it down again 😄

[IshaanDesai]

I would recommend to only add this functionality once it is really needed. I currently don't see a use case for this. Am I missing sth?

No you are right, currently there is no use case for this. It can be added if deemed necessary at a future point of time!

Is this related to the coupling? Is any preCICE functionality called there? Let's not take pure FEniCS functionality to the adapter if there is not a really good reason.

Here the setting up of boundary conditions is a mostly FEniCS side functionality but the actual values will be written to the corresponding variables and also on the mesh preCICE sees. But yes this could be done in set_coupling_mesh functionality with some additional user inputs.

Overall, I think, we need to be careful to not over-engineer this mid-level API. Let's start low and add functionality whenever necessary.

👍