High-level FV API documentation

Table of Contents

Overview

This overview of the Morfeus Finite-Volume (Morfeus-FV) framework includes a brief description of how to use the framework to set up a new solver for a system of coupled partial differential equations. The overview outlines key classes and type-bound procedures. A sample input file is provided and its components described along with instructions for

Reading input files and grid files,
Initializing the library and data structures,
Setting up PDEs and integrating the solution forward in time, and
Writing outputs.

Sphere geometry and mesh for finite volume solver

Solver Description

The morfeus solver consists of two parts:

A common library of routines for reading input files, creating the grid, discretization of the equations, solving the equations using the Parallel Basic Linear Algebra Subroutines (PSBLAS), and plotting of the results.
A problem-specific solver built using the routines from the morfeus finite volume library.

Numerical Algorithms

Morfeus-FV solves transport equations using explicit finite-difference time advancement and cell-based finite-volume scheme spatial discretizations. For a complete description of the algorithms employed in Morfeus-FV, refer to the dissertation by S. Toninel (2006). More recent work has involved modernization of the code using the modular and object-oriented programming (OOP) features of Fortran 2008, including

Type extension,
Type-bound procedures,
User-defined, type-bound operators, and
Submodules.

Input Files

Morfeus requires two input files. The first is a geometry file in GAMBIT neutral file format or in EXODUS II format; the second is a file called fast.json that contains the problem description, i.e. the description of materials, boundary conditions, solver parameters such as convergence criteria, and output parameters. The fast.json file should be present in the same folder as the mesh-file and the solver. The next several sections describe different sections of a sample json input file.

Example Program Flow

A typical multi-physics application for dealing with heat transfer, solid mechanics, and various other physics would look something like the figure below:

It might not be immediately obvious how to connect these high-level concepts to the particular objects, classes and their methods listed below. The following figure provides a mapping to connect these abstract concepts to their more concrete realization.

Additional information about the objects, classes and their mothods (type bound procedures) shown on the right hand side of the preceding figure can be found below. This information includes direct links to the more detailed API documentation.

High-Level Object Descriptions

As an illustrative example, the sample input file describes coaxial cable geometry. The input file is written using the JavaScript Object Notation (JSON) format and accessed by Morfeus via the json-fortran library. The file contains a top-level MORFEUS object, which in turn contains child objects defining various problem parameters. The child objects can occur in any order within the top-level object without affecting the functionality of the solver.

Mesh object

The MESH object in the input file describes the name and directory of the file containing the mesh geometry. The coaxial cable geometry consists of several concentric materials. All computations in morfeus are done in MKS units. Any scaling of the geometry is also specified in this object. Mesh renumbering, partitioning scheme, and mesh diagnostics output for debugging can also be specified in this object.

"MESH": {
  "mesh-dir": "./",
  "mesh-file": "coaxial_cable.e",
  "scale": 1,
  "gps-renumbering": false,
  partitioning-scheme": "Block",
  "write-matrix-pattern-diagnostics": false
}

Materials object

The MATERIALS object of the input file describes the materials used in the problem. Each material corresponds to a group of cells in the geometry file, and the materials should be listed in the same order as the cell groups in the geometry file.

"MATERIALS": {
  "copper-core": 100,
  "dielectric-insulator": 4,
  "copper-sheath": 100,
  "plastic-sheath": 402,
  "tape": 100
}

PDES object

The PDES objects describes the solver parameters for the different PDEs. It contains child objects for each of the energy, concentration and displacement PDEs that need to be solved. The Energy object describes the parameters used for the heat transfer equation, the Concentration object describes the parameters used for the diffusion equations solver, and the Displacement object describes the parameters for the solid mechanics equations solver. The main parameters defined in each of these objects are the numerical solver method for the matrix problem, the matrix preconditioner used, convergence criteria, and maximum number of interactions. For illustration, only the Energy PDE is shown below.

"Energy": {
  "convergence-method": "BICGSTAB",
  "preconditioning-method": "BJAC",
  "solve-epsilon": 1e-08,
  "max-solve-iterations": 100,
  "write-matrix-system-diagnostics": false
}

Iterations object

The iterations object contains three child objects which define the solver iterations and convergence parameters.

Time object The time object describes the number of time steps to be executed and the $\delta t$ in seconds.
Big-solver object The big-solver object describes the convergence tolerance for the iterative solver, and the maximum number of steps to be executed before moving to the next time-step.
Output object The output object describes how frequently (per how many time steps) the results should be output in the chosen format.

"iterations": {
  "time": {
    "max-steps": 200,
    "delta-t": 1
  },
  "big-solver": {
    "tolerance": 1e-08,
    "max-steps": 100
  },
  "output" : {
    "max-steps": 5
  }
}

Output object

The output object describes the output filename and format.

"output": {
  "format": "vtk",
  "base-path": "out_nemo"
}

Source terms object

The Source-terms objects contains two child objects that contain the source terms for the Energy PDE and the Concentration PDE.

"Source-terms": {
  "temperature": {
    "sc": {
      "value": 10,
      "units": "[W/m^3]"
    },
    "sp": {
      "value": 0,
      "units": "[W/m^3 K]"
    }
  },
  "concentration": {
    "sc": {
      "value": 10,
      "units": "[]"
    },
    "sp": {
      "value": 0,
      "units": "[1/K]"
    }
  }
}

Boundary conditions object

The BCS object contains a list of child objects for each boundary surface. The number of child objects should match the boundary surfaces in the geometry file and should be in the same order as the surfaces in the geometry file.

"BCS": [
  {
    "type": "wall",
    "description": "copper-core 0",
    "temperature": {
      "id" : 1,
      "value" : 500
    },
    "stress": {
      "id" : 1
    },
    "velocity": {
      "id" : 1
    }
  },
  {
    "type": "wall",
    "description": "dielectric-insulator 0",
    "temperature": {
      "id" : 2
    },
    "stress": {
      "id" : 1
    },
    "velocity": {
      "id" : 1
    }
  }
]

Table: Temperature boundary conditions

BC ID	Description	Value 1	Value 2
1	Fixed temperature	Temperature in K
2	Adiabatic BC
3	Fixed flux	flux in W/m2
4	Convection	Coeff in W/m2K	Temperature in K

Table: Stress boundary conditions

BC ID	Description	Value
1	Stress free
2	Prescribed Stress	Stress in N/m2

Table: Velocity boundary conditions

BC ID	Description	Value
1	No slip
2	Free slip
3	Sliding
4	Moving	Velocity in m/s
5	Free sliding

High-Level Classes

Below is a list of the important high-level objects and classes, with a brief discussion and links to detailed API documentation and their implementations. A complete list of all FD and FV classes and types can be found on the types list page.

object

object is an abstract type to ensure descendents declare the required deferred bindings to

Methods

mark_as_defined
user_defined

grid

grid ss the Morfeus universal base type for all grids, for FD and FV grids. It extends object.

Methods

set_units
get_units

field

field is the Morfeus base type for all fields. It extends grid.

Methods

material

material is a class to describe material state and specify state equations.

Methods

matptr

matptr is a class with a single material type object

mesh

mesh is a class to define and manipulate data describing the discretization of space into connected finite-volume cells and surfaces

Methods

create_mesh : Class constructor
free_mesh : Class destructor
check_mesh_unused_el
nemo_sizeof

bc_poly

bc_poly Implement a runtime polymorphism pattern ¹ to emulate an abstract parent of the bc_math/bc_wall classes.

Methods

scalar_source

scalar_source

Methods

Methods

High-Level Procedures

All Morfeus FV and FD procedures are listed on the procedures list page, but below is a curated list of those that correspond to high-level operations in FV. These should help you write your own programs and kernels using Morfeus FV.

assert

assert Is an assertion utility used in design by contract (DBC) for enforcing pre-conditions, post-conditions and invariants, as well in testing.

Todo

Add other stand-alone procedures used to instantiate objects of for other purposes where a TBP method is not used.

Akin, E. (2003) Object-oriented programming via Fortran 90/95. Cambridge University Press. ↩

Developer Documentation