burgers_equation.rnc

include "spud_base.rnc"

include "adaptivity_options.rnc"
include "diagnostic_algorithms.rnc"
include "input_output.rnc"
include "solvers.rnc"
include "stabilisation.rnc"
include "reduced_model.rnc"
include "mesh_options.rnc"
include "physical_parameters.rnc"
include "prognostic_field_options.rnc"
include "prescribed_field_options.rnc"
include "spatial_discretisation.rnc"
include "temporal_discretisation.rnc"

start =
   (
      ## The root node of the options dictionary.
      element burgers_equation {
         comment,
         ## Model output files are named according to the simulation
         ## name, e.g. [simulation_name]_0.vtu. Non-standard
         ## characters in the simulation name should be avoided.
         element simulation_name {
            anystring
         },
         geometry,
         io,
         timestepping,
         material_phase,
         adjoint_options?
      }
   )

geometry = 
   (
      ## Options dealing with the specification of geometry
      element geometry {
         ## Dimension of the problem.
         ## <b>This can only be set once</b>
         element dimension {
            element integer_value {
               attribute rank {"0"},
               ("1")
            }
         },
         ## The position mesh
         element mesh {
            attribute name { "CoordinateMesh" },
            mesh_info_fromfile
         },
         ## The velocity mesh
         element mesh {
            attribute name { "VelocityMesh" },
            mesh_info_frommesh
         },
         ## Quadrature
         element quadrature {
            ## Quadrature degree
            ## 
            ## note: this specifies the degree of quadrature,
            ## not the number of gauss points
            element degree {
               integer
            },
            ## Surface quadrature degree
            ## 
            ## note: this specifies the degree of surface
            ## quadrature not the number of surface gauss points
            element surface_degree {
               integer
            }?
         }
      }
   )

mesh_choice_coordinate = 
   (
      element mesh {
         attribute name { "CoordinateMesh" }
      }
   )

mesh_choice = 
   (
      (
         element mesh {
            attribute name { "VelocityMesh" }
         }|
         element mesh {
            attribute name { "CoordinateMesh" }
         }
      )
   )

mesh_info_fromfile =
   (
      ## Read mesh from file.
      element from_file {
         (
            ## Triangle mesh format.
            ##
            ## Enter the base name without the .edge .ele, .face or
            ## .node extensions, and without process numbers.
            element format {
              attribute name { "triangle" },
              comment
            }|
            ## Read the mesh from a vtu. Note that the mesh will have no 
            ## surface or region IDs.
            element format {
              attribute name { "vtu" },
              comment
            }|
            ## GMSH mesh format
            element format {
               attribute name { "gmsh" },
               comment
            }
         ),
         attribute file_name { xsd:string },
         from_file_mesh_stat_options,
         comment
      }
   )

mesh_info_frommesh =
   (
      ## Make mesh from existing mesh. 
      element from_mesh {
         mesh_choice_coordinate,
         element mesh_shape {
            element polynomial_degree {
               integer
            }?,
            element element_type {
              element string_value{
                 "lagrangian"
              }
            }?
         }?,
         derived_mesh_stat_options,
         comment
      }
   )

timestepping =
   (
         ## Options dealing with time discretisation
         element timestepping {
            ## Current simulation time. At the start of the simulation this
            ## is the start time.
            element current_time {
               real
            },
            ## The time step size. If adaptive time stepping is used
            ## then this is the initial time step size.
            element timestep {
               real
            },
            ## Simulation time at which the simulation should end.
            element finish_time {
               real
            },
            ## Timestep after which the simulation should end.
            element final_timestep {
               integer
            }?,
            ## Number of non-linear iterations.
            ## 
            ## Manual suggests 2
            element nonlinear_iterations {
               integer
            }?,
            ## Indicate that the problem should be considered time-independent.
            ## The model will pseudo-timestep to convergence, and exit from the
            ## timestepping loop when the steady state tolerance has been reached.
            element steady_state {
               ### The convergence tolerance, in the L2 norm
               element tolerance { real }
            }?               
         }
   )

material_phase = 
   (
         ## The material phase options
         element material_phase {
            attribute name { "Fluid" },
            element scalar_field {
               attribute rank { "0" },
               attribute name { "Velocity" },
               element prognostic {
                  element mesh {
                     attribute name { "VelocityMesh" }      
                  },
                  ## Options dealing with the temporal discretisation of velocity
                  element temporal_discretisation {
                     ## The degree of implicitness in the timestepping. 
                     ## 0 is fully explicit, 1 is implicit, 0.5 is Crank-Nicolson.
                     ## Recommended to be 0.5.
                     element theta { 
                        real
                     },
                     ## The relaxation term in the nonlinear iterations at each timestep
                     ## 0 means the previous timestep velocity is used to form the advection operator,
                     ## while 1 means the best guess of the next timestep velocity is used.
                     ## Recommended to be 0.5.
                     element relaxation {
                        real
                     },
                     ## If activated, the time term is removed from the equations. Should be used with theta=1 and relaxation=1.
                     element remove_time_term { empty }?
                  }?,
                  element solver {
                     linear_solver_options_asym
                  },
                  ## If activated, the advection term is removed from the equation.
                  element remove_advection_term { empty }?,
                  initial_condition_scalar,
                  boundary_conditions+,
                  element viscosity { real },
                  element stat { comment },
                  adjoint_storage,
                  element scalar_field {
                     attribute name { "Source" },
                     attribute rank { "0" },
                     element prescribed {
                        prescribed_scalar_field_no_adapt,
                        recalculation_options?
                     }
                  }?,
                  # If enabled, save the right hand side of the discrete equations.
                  element scalar_field {
                     attribute name { "Rhs" },
                     attribute rank { "0" },
                     element diagnostic {
                        empty
                     },
                     adjoint_storage
                  }?
               }
            },
            ## Prescribed or diagnostic scalar fields.
            element scalar_field {
              attribute rank { "0" },
              attribute name { string },
              (
                 element prescribed {
                    mesh_choice,
                    prescribed_scalar_field_no_adapt,
                    recalculation_options?,
                    adjoint_storage
                 }|
                 element diagnostic {
                    mesh_choice,
                    diagnostic_scalar_field,
                    adjoint_storage
                 }
              )
            }*
         }
   )

boundary_conditions = 
   (
         ## Boundary conditions
         element boundary_conditions {
            attribute name { string },
            ## Surface id
            element surface_ids {
               integer_vector
            },
            element type {
               attribute name { "dirichlet" },
               input_choice_real
            }
         }
   )

prescribed_output_options = empty
prescribed_detector_options = empty
prescribed_scalar_stat_options = empty
discrete_properties_algorithm_scalar = empty
recalculation_options =                                                                                                                                                                                                                      
   (
      ## Prevent this field from being recalculated at every timestep.
      ## This is cheaper especially if you are enforcing discrete properties on the field.
      element do_not_recalculate {
        empty
      }
   )

diagnostic_scalar_field =
   (
      scalar_python_diagnostic_algorithm,
      element stat { comment },
      recalculation_options?
   )

adjoint_storage =
   (
      ## Informs the model whether the field should be computed only in the
      ## forward model, the adjoint model, or in both.
      ## If /adjoint is not enabled, this has no effect whatsoever.
      element adjoint_storage {
         (
            ## Include the field in both the forward and adjoint states.
            element exists_in_both {
               ## If enabled, this element tells the model that this field must be stored
               ## through time in order to compute the adjoint model.
               element record { empty }?
            }|
            ## Include the field only in the forward state.
            element exists_in_forward {
               ## If enabled, this element tells the model that this field must be stored
               ## through time in order to compute the adjoint model.
               element record { empty }?
            }|
            ## Include the field only in the adjoint state.
            element exists_in_adjoint {
               empty
            }
         )
      }
   )

adjoint_options =
   ## Turn on the solution of the adjoint problem.
   ## To compute the adjoint you must either specify code for the functional
   ## or for its derivative. If the derivative is not specified, then
   ## the independent set perturbation method will be used to approximate
   ## its derivative. 
   element adjoint {
      ## The functional to be computed.
      ## If the derivative is not specified, then the independent set perturbation
      ## method will be employed to approximate its derivative.
      ## FIXME: needs more documentation
      element functional {
        ## Python code for the functional
        element algorithm {
           attribute name { "functional" },
           python_code
        }
      }?,
      ## The derivative of the functional. If this is specified, then
      ## the derivative can be computed exactly and more efficiently than
      ## if the independent set perturbation method is employed to approximate it.
      element functional_derivative {
        ## Python code for the functional derivative
        element algorithm {
           attribute name { "functional_derivative" },
           python_code
        }
      }?
   }

io =
   ## Options to do with I/O
   element io {
     ## Dump format
     element dump_format { "vtk" },
     ## Dump period, in timesteps. Defaults to 1
     element dump_period_in_timesteps { 
       element constant { integer }
     }?,
     (
        ## The mesh on to which all the fields will be
        ## interpolated for VTK output.
        element output_mesh {
           attribute name { "VelocityMesh" }
        }|
        ## The mesh on to which all the fields will be
        ## interpolated for VTK output.
        element output_mesh {
           attribute name { xsd:string }
        }
     )
  }