Portage provides very crude mesh and state manager frameworks aptly called Simple_Mesh and Simple_State through its support package, Wonton. The goal of these frameworks is to show how one can wrap their favorite mesh and state manager for use with Portage - they should not be used in any production sense. The details on the Wonton::Simple_Mesh and Wonton::Simple_State frameworks, and its wrappers Wonton::Simple_Mesh_Wrapper and Wonton::Simple_State_Wrapper, can be found in the Wonton documentation.
Wrappers
As mentioned on the Concepts page, the search, intersect, and interpolate actions in Portage all operate on mesh and particle wrappers for geometry and topology access, and state wrappers for data access. The reason for using wrapper classes instead of the native classes directly is that Portage may need some information that may not be readily available within the original mesh/particle and state frameworks, but could be constructed within a wrapper.
Portage's support package, Wonton, provides a helper class, Wonton::AuxMeshTopology, that assists in extending a basic mesh's topological entities needed for some remap capabilities. One does not need to use the AuxMeshTopology class, especially if one's mesh already efficiently supports the advanced mesh topologies. In particular, the advanced mesh topologies and entities, which we term sides, corners, and wedges are utilized in node-centered remapping, but are also required if there are cells with non-planar faces in the remap.
Putting it all Together
Let us illustrate the usage of Portage with a few lines of code. First, we create two square meshes in a unit square domain with 16 and 25 computational cells, respectively:
Then, we wrap the meshes with a Portage-compatible wrapper
Assuming that we have cell data inputData for the source mesh, we need to register data with state wrappers
Now, we are ready to call a driver to perform remap of inputData from sourceMesh to the targetMesh via the wrappers:
Here, dim=2 is referring to number of spatial dimensions of the problem, remap_fields is a vector containing a string "celldata", and the first three arguments represent particular methods of search, intersect, and interpolate steps as described in Concepts.
This simple example covers an atypical case where we do not have a source mesh nor any field data on it. Therefore, we added a state vector initialized from our own data vector called inputData. Normally, however, the source mesh would already have such a field on it and we would just have to add empty data to the target mesh to make sure we can remap into it.
In the next example, we demonstrate a more typical situation of reading source and target meshes from files source.exo and target.exo using Jali. Instead of using the driver, we instantiate Search, Intersect and Interpolate classes directly:
We create a native Jali state manager for a source mesh.
Additionally, we can add cell data from a vector sourceData to a state manager.
Next, we read and wrap a target mesh and add empty data to it.
Both meshes are wrapped for interfacing with the underlying mesh data structures.
We get an instance of the desired search algorithm type in dim spatial dimensions for a cell field.
Now, we apply Portage wrappers for source and target fields.
Further, we make an intersector which knows about the source state (to be able to query the number of materials, etc). DummyInterfaceReconstructor and two void arguments indicate that we want to perform intersections of a single-material filed.
Finally, we get an instance of the desired interpolate algorithm type.
Existing Applications and Tests
Nearly all of the generic unit tests have been designed to work with the Wonton::Simple_Mesh_Wrapper and Wonton::Simple_State_Wrapper data structures when a mesh with a topology and field data are required. These should serve as examples of the types of things one may want to do with a mesh and state framework.
Simple_mesh_app
Better examples of how to use these wrappers to actually do a remap of field data are in the application tests. In particular, the app/simple_mesh_app/simple_mesh_app.cc program shows how to wrap mesh and state objects, adds some field data to the source state, and utilize Portage::MMDriver with various search, intersect, and interpolate algorithms to perform the remap. The Portage::MMDriver is templated on mesh wrapper type and state wrapper type, and can be used with other frameworks. Portage::MMDriver and Portage::SwarmDriver are a good starting point for writing one's own remap application.
Portageapp_jali
This application demonstrates how to remap (scalar) field data using the Jali mesh infrastructure. The application app/portageapp/portageapp_jali.cc is capable of remapping cell and nodal fields defined on square/cubic meshes or on unstructured meshes in 2D and 3D, respectively.
The app allows users to specify an analytic field on a source mesh. This is done by an algebraic expression in the standard input, see options and examples below. The app can also remap all the fields that are on a source mesh that is read from a file. An error of remap is calculated by comparing remapped values to exact values in the cell-centroids/nodes on a target mesh and the error is printed to standard output. The remapped field on a target mesh is saved into a file output.exo if it is not specified otherwise. The app can be run using e.g.
More options can by explored by executing
Portageapp_multimat_jali
Similar to portageapp_jali for mesh fields, app/portageapp/portageapp_multimat_jali demonstrates Portage's ability to remap multi-material fields. In order to preserve sharp interfaces between materials, Portage relies on Tangram to perform interface reconstruction on the source mesh. Reconstructed material polygons are intersected with cells on a target mesh. An input file specifying volume fractions (and optionally material centroids for MOF) is required in addition to the meshes and multiple material fields. For now, this app works only in serial.