Standardize input options and clean up demos

[jeff-cohere]

Our demos do a lot of work that could be done automatically by the dycore during its initialization:

• reading in a mesh file
• extruding the mesh
• distributing the mesh
• setting the type of boundary condition for the domain
• reading initial conditions from a file

New Developments

As explained more in #211 and #197, we're rethinking the TDycore interface to simplify the dycore's role to set up a DM and hand it to a solver to run a simulation. In #212, we admit this lower-level approach won't work for everyone and plan to establish a separate high-level interface for folks who just want buttons for initialize, advance/step, and finalize.

The solver-centric approach encourages us to focus on the DM as the problem speification, and the dycore as the thing that creates it from a user's description. This means that a DM originates from a dycore, and therefore that TDySetDM is a complication we don't need. See below for a description of how the dycore aims to create its DM given options.

TDycore approach for setting options

We now rely on TDySetFromOptions to accept all command line options from the supported list.

Options currently implemented

• -tdy_gravity - sets the magnitude of the gravitational vector
• -tdy_init_with_random_field - initializes the solution with a random field
• -tdy_init_file - specifies an initial conditions file
• -tdy_mode - Flow mode
• -tdy_method - Discretization used by the model
• -tdy_mpfao_boundary_condition_type - type of boundary condition
• -tdy_mpfao_gmatrix_method - MPFA-O gmatrix method
• -tdy_output_mesh - Enable output of mesh attributes
• -tdy_permeability - sets the (constant, scalar) permeability value
• -tdy_porosity - sets the (constant) porosity value
• -tdy_quadrature - set quadrature type (FE only?)
• -tdy_regression_test - Enable output of a regression file
• -tdy_read_mesh <mesh_file> - specifies a file from which a mesh is to be read
• -tdy_pressure_bc <value_or_func> - assigns a named pressure boundary condition to the domain boundary
• -tdy_velocity_bc <value_or_func> - assigns a named velocity boundary condition to the domain boundary
• -tdy_soil_density - sets the (constant) soil density value
• -tdy_soil_specific_heat - sets the (constant) soil specific heat value
• -tdy_thermal_conductivity - sets the (constant, scalar) thermal conductivity value
• -tdy_tpf_allow_all_meshes - Enable to allow non-orthgonal meshes in tpf
• -tdy_water_density - Water density type (constant or exponential)
• -tdy_residual_satuaration - sets the (constant) value for residual saturation
• -tdy_gardner_param_n - sets the Gardner n parameter
• -tdy_vangenuchten_param_m - sets the VanGenuchten m parameter
• -tdy_vangenuchten_param_alpha - sets the VanGenuchten alpha parameter

If -tdy_read_mesh is supplied with a filename, the dycore creates a DM from the mesh in the given file. If this option is not given, the dycore creates a DM and applies all relevant PETSC DM options. The resulting mesh is then distributed, and any necessary overlapping mesh points are added.

If no mesh options are given at all, the dycore generates its "default" mesh, which is an 8x8x8-cell unit cube. If you don't ask for anything, you can't really complain!

If you want to make a demo with a mesh of a fixed type for some exotic purpose, you can always get the dycore's DM using TDyGetDM before TDySetup, and call PETSc's DM* functions to set it up.

Options still to be implemented

• -tdy_forcing - selects a named forcing function
• -tdy_permeability <value_or_func> - sets the (constant, scalar) permeability or selects a named function
• -tdy_porosity <value_or_func> - sets the (constant) porosity or selects a named function
• -tdy_soil_density <value_or_func> - sets the (constant) soil density value or selects a named function
• -tdy_soil_specific_heat <value_or_func> - sets the (constant) soil specific heat value or selects a named function
• -tdy_thermal_conductivity <value_or_func> - sets the (constant, scalar) thermal conductivity or selects a named function

In the cases of parameters accepting <value_or_func>, we break each argument up into two distinct arguments, e.g. -tdy_porosity_value <value> and -tdy_porosity_func <func>.

Options to be deleted

• -tdy_mpfao_boundary_condition_type (can be inferred from given BC functions)

[jedbrown]

If you're okay to work with PETSc main, then all meshes can be read, distributed, and extruded with

DMCreate(comm,&dm);
DMSetType(dm, DMPLEX);
DMSetFromOptions(dm);

https://petsc.org/main/docs/manualpages/DM/DMSetFromOptions.html

[jeff-cohere]

Just a note, in case we do decide to update to a more recent PETSc: the location of the headers supplying khash, which our timers use, has changed. We'll have to make a decision about when we switch and then apply a code change.

UPDATE: We've updated our supported PETSc version, so this work is done.

[bishtgautam]

How about splitting -tdy_thermal_conductivity <value_or_func> in two options one for value and one for function?

[jeff-cohere]

I've updated the description of this issue to reflect the work that's been done. It'll be easier to finish the rest and clean up our demos once we discuss #200.