-
Notifications
You must be signed in to change notification settings - Fork 116
Fluidity options and diamond
This page documents the new system of options which is implemented for Fluidity. The goal of the new options system is to provide a comprehensive, replacement for the options system which is easy for users to use and which facilitates developers adding new options.
Diamond is executed using the following command:
[DIAMOND PATH]diamond [OPTIONS] ... [FILE]
Run "diamond -h" for full usage information.
[http://psyco.sourceforge.net/ Psyco] is a Python module that increases the speed of Python code without the need for code modification. Diamond will make use of Psyco if it is available on your system. On Ubuntu systems Psyco can be installed using the command:
sudo apt-get install python-psyco
Alternatively, download and extract Psyco from the Psyco website, and add the Psyco directory to your PYTHONPATH environment variable.
The documentation widget supports the use of Pango text attribute markup language in element documentation ([http://library.gnome.org/devel/pango/unstable/PangoMarkupFormat.html see here for details]). In Relax NG compact notation this can used directly, e.g:
## This text is <b>bold</b>;
In Relax NG XML notation the Pango markup must be entered using XML entities in order to avoid confusion with the schema XML, e.g:
<a:documentation>This text is <b>bold</b></a:documentation>
Internet links of the form "http://[link]" are automatically detected by the documentation widget and converted to hyperlinks. Clicking on these hyperlinks will open the link in a web browser. Spaces and newlines are used to find the ends of documentation links, and trailing punctuation marks (e.g. full stops and close brackets) are not added to the generated hyperlink.
- Choice nodes must be choices between single elements (e.g. a choice between a OR (b AND c) is invalid).
- Elements with the same tag under the same parent are allowed. However, at most one can be + (oneOrMore) or * (zeroOrMore). Elements with the same tag under the same parent must each have a name attribute with a unique value.
- The problem geometry may only be set once. Once the geometry has been set the GUI will lock the geometry/dimension data. This is necessary in order for dimensional data to be displayed correctly.
- "name" attributes may contain only alpha-numeric characters, or characters in "/_:[]"
- Empty string data or attribute values are not permitted.
- Recursive schema elements are not supported.
- Data type tooltips (visible by hovering over attributes or data) require PyGTK 2.12. Tooltips will not be displayed if using an older version of PyGTK.
Fluidity uses the spud-Local:Diamond options system. The ic composed of three parts:
- An options schema, defining the valid model options, written in [http://www.relaxng.org RelaxNG] schema language.
- Local:Diamond which processes the schema to produce a graphical user interface via which the user can create XML options files that validate against the given schema.
- spud, which processes the XML options files to produce a global options dictionary accessible within the model.
The libspud API is fully documented in the spud-Diamond manual, found at libspud/doc/spud_manual.pdf.
A dictionary is a data structure in which data objects are stored indexed by a key. For the purposes of the libspud options dictionary, the key is always a string so the options dictionary can be thought of as a system by which the value of an option is accessed by providing its name.
For example the name of the current simulation can be accessed using the Fortran call:
call get_option("/simulation_name", name)
Options may be integer, real or logical or character and the get_option subroutine interface is overloaded to return any of these types. The correct option may be queried using:
option_type = option_type(key)
where key is a character variable containing the name of the option being queried. Option_type returns an integer which takes a value given by the paramenters:
SPUD_REAL
SPUD_INTEGER
SPUD_LOGICAL
SPUD_CHARACTER
Due to the strong typing employed in Fortran, querying option type is mostly of use for debugging. Routines also exist to query the shape and rank of options. In addition, the presence of an option can be queried with the logical function:
has_option(key)
Options are arranged in a hierarchical tree structure similar to a computer directory tree. This reflects the natural association of options with objects, especially fields in the tree. For example, the timestep is available as the option "/timestepping/dt"
The basic object of the finite element method is the field. In particular, the fields representing prognostic variables are the key objects for which we solve the equations. It is natural therefore that the options are focussed around these fields. For multiphase flows fields are grouped together by the phase to which they apply.
The grammar of the options XML file is specified in the Relax NG schema fluidity_options.rnc in the tools directory. This schema is in Relax NG compact notation which is most suitable for editing by hand. Diamond, the new options gui, needs the schema in Relax NG XML notation so it is always necessary to generate the new XML form every time the compact form is edited. spud-preprocess uses [http://www.thaiopensource.com/relaxng/trang.html Trang] to convert from Relax NG compact notation to Relax NG XML notation:
spud-preprocess fluidity_options.rnc
There is a useful [http://books.xmlschemata.org/relaxng/page2.html book on Relax NG] and a [http://relaxng.org/compact-tutorial-20030326.html tutorial on the compact syntax].
(X)Emacs has a mode for editing rnc schemas. On Debian/Ubuntu simply type:
wajig install rnc-mode
then in the tools directory:
xemacs fluidity_options.rnc
The preferred way of writing options files is using the gui. However for debugging it can be useful to edit options files by hand in a text editor. There is an xml mode for Emacs (but not XEmacs) which supports Relax NG schemas. To install it on Debian/Ubuntu type:
wajig install nxml-mode
For documentation on how to use nxml-mode see http://www.thaiopensource.com/nxml-mode/
It is important for both usability and maintainability that the options system is internally consistent.
The following excerpt from the schema describes the option for the current simulation time:
## Current simulation time. At the start of the simulation this
## is the start time.
element current_time {
attribute replaces {"ACCTIM"},
real
}
The following sections describe the conventions for various parts of element definitions.
Option names must be all lower case with spaces indicated by "_". For example the format of output files in the schema is "dump_format". Use full words and be descriptive: the idea is that a user should be able to read an options name and know immediately what it is for. Be very conservative about abbreviating names. If you even suspect that a new user might not understand your abbreviation, don't use it!
Every option must have a user annotation which contains documentation for users setting that option. Annotations are placed in the schema file immediately before the element they describe and are marked by a double comment character "##". The annotation must go on the lines immediately above the element.
In the case of named patterns, the annotation must go immediately above where the pattern is defined, not where it is referred to.
Where an option is a drop in replacement for a Gem option, a "replaces" attribute should be supplied whose value is the Gem option which is replaced. Where an option replaces multiple Gem options, the value should be a space separated list of gem option names:
"HMAXXX HMAXXY HMAXXZ HMAXYY HMAXYZ HMAXZZ"
There are a number of forms which the data content of an option can take. Many of these are defined by named patterns so that the same element defining a data type appears at many locations in the schema.
The "anystring" named pattern encodes general string data. The "filename" and "python_code" patterns are available to encode filenames and python code respectively and the creation of more specific string formats is encouraged. In each case the contents are still simply a string but the specification of additional information may be of use to the gui.
The simplest real data pattern is "real". This is the pattern for options which take a single real number. The next most common option is for a vector of real numbers with length equal to the dimension of the problem (usually 3). The pattern for this is "real_dim_vector". It is also possible to specify that a vector may be of arbitrary length by providing "real_vector". The full list of real patterns is:
| real | A single real value | | real_vector | An arbitrary length real vector | | real_dim_vector | A vector with length equal to the problem dimension | | real_tensor | An arbitrary shape rank 2 tensor | | real_dim_tensor | An n x n tensor where n is the problem dimension | | real_dim_symmetric_tensor | As above but constrained to be symmetric |
Integer data types are similar to real types. Currently not all variants are in the schema but it is easy to add them as they are needed.
Consistent indentation makes a massive difference to the readability of the file. The following codifies the current practice in the schema. Please comply with it. If you think the schema would be better indented in a different way, please start a discussion among the developers about it, rather than just starting to do something different.
- Indentations steps are always 3 spaces. There are no tabs.
- There is only ever 1 element, attribute or named pattern reference on a line.
- There is only ever 1 closing bracket ( ) or } ) on a line.
The comment preceding an element is indented to the same degree as the element definition. The first line of the element definition has the form:
element element_name {
The contents of the element are indented by 3 spaces and the closing } is on a new line at the same indentation as the element definition. If the closing } is followed by any of |,+?* then these symbols are on the same line as the }. Nothing else appears on the same line as the }.
## The name of the simulation
element simulation_name {
anystring
},
Attribute definitions are indented 3 spaces from their surrounding element definition. Usually the entire attribute definition is on one line, including any trailing , or |
element mesh {
attribute name { "CoordinateMesh" },
mesh_info
},
The first line of the named pattern definition contains only the pattern name and =. The body of a named pattern must always be contained in brackets with the opening bracket indented 3 spaces on the next line. The body of the bracket group is indented a further 3 spaces so that the contents of the named pattern are effectively double indented.
real
(
element real_value{
attribute rank { "0" },
list {xsd:float}
},
comment
)
See Local:Diamond#Limitations for GUI specific limitations.
When the Fluidity options schema is changed, existing FLML files may no longer be consistent with the Fluidity schema - i.e. an old FLML file may not validate against an updated schema. Local:Diamond deals with this by discarding any information found in FLML files that can not be made consistent with the FLML definition in the Fluidity options schema.
Only certain characters are recognised by the options dictionary, which contains the flml input once it is read into fluidity. Therefore only the following letters are allowed in any input field:
/_:[]1234567890qwertyuioplkjhgfdsazxcvbnmMNBVCXZASDFGHJKLPOIUYTREWQ
Comment boxes may contain any characters.
Names of objects (fields, material phases, meshes etc.) should be camel cased (MyOwnField) and not contain spaces or underscores. Furthermore, the characters /:[] are prohibited as these have special meanings in the options dictionary inside Fluidity.
The simulation name is the base name for all output files. For example if you set the simulation name to foo then your statistics output file will be called foo.stat
Setting problem type gives fluidity a hint as to what sort of simulation you are conducting and therefore what combinations of options are likely to be valid. If you do not know which category applies to your problem, choose "fluids"
The dimension of the domain of your problem. For most users this should be set to 3. Be careful, once you set the dimension you can't change it again!
Meshes are the finite element spaces on which your problem is solved. Meshes are either read from file or are derived from other meshes.
This causes the mesh to be read from an external file (or set of triangle files). For the moment only triangle format is supported so ensure the format is set to "triangle". Set the file_name attribute of from_file to the name of the file in which your mesh is stored. In the case of triangle files, do not include the file extension (.node etc.) but do include the iteration number if present (eg .1).
You can either produce a triangle file directly or convert it from another format:
- Local:Mesh generation with gmsh
- Local:gem2triangle
- GiD meshes can be converted to triangle meshes using the gid2triangle tool.
This causes the mesh to be based on another mesh. In the simplest case, this can be used to indicate that two meshes are the same. For example, to specify that the VelocityMesh is the same as the CoordinateMesh, set VelocityMesh to "from_mesh" and choose "mesh(CoordinateMesh)".
In more complex cases, the new mesh might have different continuity or degree from the old mesh. To specify a discontinuous mesh, enable mesh_continuity and select "discontinuous". To specify a different polynomial degree, enable mesh_shape and set "polynomial_degree".
You must always have a CoordinateMesh, VelocityMesh and PressureMesh. You may optionally have any number of additional meshes. Unless you know you need discontinuous, higher degree or periodic meshes, you should set your meshes as follows:
; CoordinateMesh : from_file and specify the correct triangle file name. ; VelocityMesh : from_mesh, choose mesh(CoordinateMesh) and no other options. ; PressureMesh : from_mesh, choose mesh(CoordinateMesh) and no other options.
To use the mixed continuous/discontinuous formulation, use:
; CoordinateMesh : from_file and specify the correct triangle file name. ; VelocityMesh : from_mesh, choose mesh(CoordinateMesh), enable mesh_continuity and set it to "discontinuous". ; PressureMesh : from_mesh, choose mesh(CoordinateMesh), enable mesh_shape and set polynomial_degree to 2.
Quadrature controls the accuracy of the integration in your finite element discretisation. Setting the quadrature degree low reduces assembly time but also reduces accuracy. A good rule of thumb is that the quadrature degree should be twice the degree of your highest degree elements plus 1. Since many fluidity simulations use quadratic elements at some stage, a quadrature degree of 5 is a good default guess.
It is not usually necessary to separately set surface_degree or controlvolume_surface_degree.
These options are required if you are running an ocean simulation with a free surface or with various other ocean options which require the code to know where the ocean surface and bed lie. top_surface_ids and bottom_surface_ids are lists of boundary tags from your input mesh which lie on the ocean surface and bed respectively.
It is not usually necessary to change the settings for either of the scalar fields under this option.
io controls the frequency and form of model outputs.
Whether to dump vtk files or the old fluidity dumpfiles. Unless you know there is a particular reason to choose the old mechanism, set this to vtk. Support for dumpfiles will be dropped at some point in the future.
This is the interval between the state fields being output to disk. You should usually start by setting this to a rather low value (possibly as short as your timestep) for testing and then increase it for production runs once you know your configuration works.
It is possible to swap dump_period for dump_period_in_timesteps to specify that you wish to have a dump every fixed number of timesteps.
All fields will be interpolated onto the same mesh for output. Usually the VelocityMesh is the right choice but it can be necessary to change this if, for example, the domain is periodic.
This is the model time at the start of the simulation. You probably want to set this to 0.0
The simulation timestep. Presumably you know what you need taking into account the timescales of the simulation you are conducting and considerations such as CFL number.
The model time at which the simulation should halt. Note that the simulation may overrun slightly due to roundoff in calculating the current time or if the timestep does not divide the simulation time exactly.
Nonlinear quantities in the equations are represented by their last known values. It may be necessary to solve the equations more than once to produce better approximations to those last known values for reasons of accuracy or stability. Unless there are reasons to do otherwise, set this value to 2.
If you care about gravity (and you usually do) then you will need to specify the magnitude of the acceleration due to gravity (9.8 in SI units) and a vector field specifying the direction in which gravity points. For a 3D simulation in a flat domain, you should set value(WholeMesh) for this field to the vector (0.0, 0.0, -1.0).
ICOM supports the specification of the Coriolis acceleration in a number of different ways. The conventional options f-plane, beta-plane, sine of latitude are joined by on_sphere which handles simulations on the surface of the sphere in 3D Cartesian space. Choose the appropriate entry for your scenario and read the detailed documentation in Diamond for the selected option.
For non-ocean scenarios, leave this option unset.
A material_phase element groups all of the fields which pertain to one phase of one material. You therefore need one material_phase element for each phase of each material which you are modelling. For oceans users this will always be one material phase.
You must give each of your material phases a name.
You only require an equation of state if the density (or the perturbation density in the case of the Bousinesq equations) varies as a function of the temperature, salinity and/or pressure. If you are solving a problem in which the density is held constant, leave equation_of_state unselected.
Under equation of state, choose fluids for fluids simulations and multimaterials for multimaterial simulations. For simple oceans problems, a linear equation of state is appropriate. Under this option, it is usually advisable to enable the "subtract_out_hydrostatic_pressure" option.
You should always enable the Pressure field. If you are solving a restricted set of equations with no pressure term, set the pressure field to "prescribed" with a constant value of 0.
In the usual case, Pressure is a prognostic field.