Mercurial > repos > public > sbplib_julia

annotate docs/src/operator_file_format.md @ 989:7bf3121c6864 feature/stencil_set_type

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Add type StencilSet
author Vidar Stiernström <vidar.stiernstrom@it.uu.se>
date Thu, 17 Mar 2022 21:31:20 +0100
parents fe8fe3f01162
children 99d1f5651d0b
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
852
510f744d0876 Add some documentation for the file format
Jonatan Werpers <jonatan@werpers.com>
parents:
diff changeset
1 # Operator file format
510f744d0876 Add some documentation for the file format
Jonatan Werpers <jonatan@werpers.com>
parents:
diff changeset
2
510f744d0876 Add some documentation for the file format
Jonatan Werpers <jonatan@werpers.com>
parents:
diff changeset
3 The intention is that Sbplib.jl should be a general and extensible framework
510f744d0876 Add some documentation for the file format
Jonatan Werpers <jonatan@werpers.com>
parents:
diff changeset
4 for working with finite difference methods. It therefore includes a set of
510f744d0876 Add some documentation for the file format
Jonatan Werpers <jonatan@werpers.com>
parents:
diff changeset
5 tools for storing and sharing operator definitions as well as a set of widely
510f744d0876 Add some documentation for the file format
Jonatan Werpers <jonatan@werpers.com>
parents:
diff changeset
6 used operators.
510f744d0876 Add some documentation for the file format
Jonatan Werpers <jonatan@werpers.com>
parents:
diff changeset
7
510f744d0876 Add some documentation for the file format
Jonatan Werpers <jonatan@werpers.com>
parents:
diff changeset
8 ## Using the included operators
510f744d0876 Add some documentation for the file format
Jonatan Werpers <jonatan@werpers.com>
parents:
diff changeset
9
510f744d0876 Add some documentation for the file format
Jonatan Werpers <jonatan@werpers.com>
parents:
diff changeset
10 Most users will likely access the included operators by simply passing the
510f744d0876 Add some documentation for the file format
Jonatan Werpers <jonatan@werpers.com>
parents:
diff changeset
11 filename of the wanted operator set to the appropriate function. The location
510f744d0876 Add some documentation for the file format
Jonatan Werpers <jonatan@werpers.com>
parents:
diff changeset
12 of the included stencil sets can be computed using
510f744d0876 Add some documentation for the file format
Jonatan Werpers <jonatan@werpers.com>
parents:
diff changeset
13 [`sbp_operators_path`](@ref).
510f744d0876 Add some documentation for the file format
Jonatan Werpers <jonatan@werpers.com>
parents:
diff changeset
14 ```@meta
510f744d0876 Add some documentation for the file format
Jonatan Werpers <jonatan@werpers.com>
parents:
diff changeset
15 # TODO: provide examples of functions to pass the files to
510f744d0876 Add some documentation for the file format
Jonatan Werpers <jonatan@werpers.com>
parents:
diff changeset
16 ```
510f744d0876 Add some documentation for the file format
Jonatan Werpers <jonatan@werpers.com>
parents:
diff changeset
17 Advanced user might want to get access to the individual objects of an
510f744d0876 Add some documentation for the file format
Jonatan Werpers <jonatan@werpers.com>
parents:
diff changeset
18 operator file. This can be accomplished using functions such as
989
7bf3121c6864 Add type StencilSet
Vidar Stiernström <vidar.stiernstrom@it.uu.se>
parents: 853
diff changeset
19 * [`StencilSet`](@ref)
852
510f744d0876 Add some documentation for the file format
Jonatan Werpers <jonatan@werpers.com>
parents:
diff changeset
20 * [`parse_scalar`](@ref)
510f744d0876 Add some documentation for the file format
Jonatan Werpers <jonatan@werpers.com>
parents:
diff changeset
21 * [`parse_stencil`](@ref)
510f744d0876 Add some documentation for the file format
Jonatan Werpers <jonatan@werpers.com>
parents:
diff changeset
22 * [`parse_tuple`](@ref)
510f744d0876 Add some documentation for the file format
Jonatan Werpers <jonatan@werpers.com>
parents:
diff changeset
23
510f744d0876 Add some documentation for the file format
Jonatan Werpers <jonatan@werpers.com>
parents:
diff changeset
24 When parsing operator objects they are interpreted using `Rational`s and
510f744d0876 Add some documentation for the file format
Jonatan Werpers <jonatan@werpers.com>
parents:
diff changeset
25 possibly have to be converted to a desired type before use. This allows
510f744d0876 Add some documentation for the file format
Jonatan Werpers <jonatan@werpers.com>
parents:
diff changeset
26 preserving maximum accuracy when needed.
510f744d0876 Add some documentation for the file format
Jonatan Werpers <jonatan@werpers.com>
parents:
diff changeset
27 ```@meta
510f744d0876 Add some documentation for the file format
Jonatan Werpers <jonatan@werpers.com>
parents:
diff changeset
28 # TBD: "possibly have to be converted to a desired type before use" Is this the case? Can it be fixed?
510f744d0876 Add some documentation for the file format
Jonatan Werpers <jonatan@werpers.com>
parents:
diff changeset
29 ```
510f744d0876 Add some documentation for the file format
Jonatan Werpers <jonatan@werpers.com>
parents:
diff changeset
30
510f744d0876 Add some documentation for the file format
Jonatan Werpers <jonatan@werpers.com>
parents:
diff changeset
31 ## File format
510f744d0876 Add some documentation for the file format
Jonatan Werpers <jonatan@werpers.com>
parents:
diff changeset
32 The file format is based on TOML and can be parsed using `TOML.parse`. A file
510f744d0876 Add some documentation for the file format
Jonatan Werpers <jonatan@werpers.com>
parents:
diff changeset
33 can optionally start with a `[meta]` section which can specify things like who
510f744d0876 Add some documentation for the file format
Jonatan Werpers <jonatan@werpers.com>
parents:
diff changeset
34 the author was, a description and how to cite the operators.
510f744d0876 Add some documentation for the file format
Jonatan Werpers <jonatan@werpers.com>
parents:
diff changeset
35
510f744d0876 Add some documentation for the file format
Jonatan Werpers <jonatan@werpers.com>
parents:
diff changeset
36 After the `[meta]` section one or more stencil sets follow, each one beginning
510f744d0876 Add some documentation for the file format
Jonatan Werpers <jonatan@werpers.com>
parents:
diff changeset
37 with `[[stencil_set]]`. Each stencil set should include descriptors like
510f744d0876 Add some documentation for the file format
Jonatan Werpers <jonatan@werpers.com>
parents:
diff changeset
38 `order`, `name` or `number_of_bondary_points` to make them unique within the
510f744d0876 Add some documentation for the file format
Jonatan Werpers <jonatan@werpers.com>
parents:
diff changeset
39 TOML-file. What descriptors to use are up to the author of the file to decide.
510f744d0876 Add some documentation for the file format
Jonatan Werpers <jonatan@werpers.com>
parents:
diff changeset
40
510f744d0876 Add some documentation for the file format
Jonatan Werpers <jonatan@werpers.com>
parents:
diff changeset
41 Beyond identifying information the stencil set can contain any valid TOML.
510f744d0876 Add some documentation for the file format
Jonatan Werpers <jonatan@werpers.com>
parents:
diff changeset
42 This data is then parsed by the functions creating specific operators like
510f744d0876 Add some documentation for the file format
Jonatan Werpers <jonatan@werpers.com>
parents:
diff changeset
43 ``D_1`` or ``D_2``.
510f744d0876 Add some documentation for the file format
Jonatan Werpers <jonatan@werpers.com>
parents:
diff changeset
44
510f744d0876 Add some documentation for the file format
Jonatan Werpers <jonatan@werpers.com>
parents:
diff changeset
45 ### Numbers
510f744d0876 Add some documentation for the file format
Jonatan Werpers <jonatan@werpers.com>
parents:
diff changeset
46 Number can be represented as regular TOML numbers e.g. `1`, `-0.4` or
510f744d0876 Add some documentation for the file format
Jonatan Werpers <jonatan@werpers.com>
parents:
diff changeset
47 `4.32e-3`. Alternatively they can be represented as strings which allows
853
fe8fe3f01162 Docs touch up
Jonatan Werpers <jonatan@werpers.com>
parents: 852
diff changeset
48 specifying fraction e.g. `"1/2"` or `"0"`.
852
510f744d0876 Add some documentation for the file format
Jonatan Werpers <jonatan@werpers.com>
parents:
diff changeset
49
510f744d0876 Add some documentation for the file format
Jonatan Werpers <jonatan@werpers.com>
parents:
diff changeset
50 All numbers are accurately converted to `Rational`s when using the
510f744d0876 Add some documentation for the file format
Jonatan Werpers <jonatan@werpers.com>
parents:
diff changeset
51 [`parse_scalar`](@ref) function.
510f744d0876 Add some documentation for the file format
Jonatan Werpers <jonatan@werpers.com>
parents:
diff changeset
52
510f744d0876 Add some documentation for the file format
Jonatan Werpers <jonatan@werpers.com>
parents:
diff changeset
53 ### Stencils
510f744d0876 Add some documentation for the file format
Jonatan Werpers <jonatan@werpers.com>
parents:
diff changeset
54 Stencils are parsed using [`parse_stencil`](@ref). They can be specified
510f744d0876 Add some documentation for the file format
Jonatan Werpers <jonatan@werpers.com>
parents:
diff changeset
55 either as a simple arrays
510f744d0876 Add some documentation for the file format
Jonatan Werpers <jonatan@werpers.com>
parents:
diff changeset
56 ```toml
510f744d0876 Add some documentation for the file format
Jonatan Werpers <jonatan@werpers.com>
parents:
diff changeset
57 stencil = ["-1/2","0", "1/2"]
510f744d0876 Add some documentation for the file format
Jonatan Werpers <jonatan@werpers.com>
parents:
diff changeset
58 ```
510f744d0876 Add some documentation for the file format
Jonatan Werpers <jonatan@werpers.com>
parents:
diff changeset
59 which assumes a centered stencil. Or as a TOML inline table
510f744d0876 Add some documentation for the file format
Jonatan Werpers <jonatan@werpers.com>
parents:
diff changeset
60 ```toml
510f744d0876 Add some documentation for the file format
Jonatan Werpers <jonatan@werpers.com>
parents:
diff changeset
61 stencil = {s = ["-24/17", "59/34", "-4/17", "-3/34", "0", "0"], c = 1},
510f744d0876 Add some documentation for the file format
Jonatan Werpers <jonatan@werpers.com>
parents:
diff changeset
62 ```
510f744d0876 Add some documentation for the file format
Jonatan Werpers <jonatan@werpers.com>
parents:
diff changeset
63 which allows specifying the center of the stencil using the key `c`.
510f744d0876 Add some documentation for the file format
Jonatan Werpers <jonatan@werpers.com>
parents:
diff changeset
64
510f744d0876 Add some documentation for the file format
Jonatan Werpers <jonatan@werpers.com>
parents:
diff changeset
65 ## Creating your own operator files
510f744d0876 Add some documentation for the file format
Jonatan Werpers <jonatan@werpers.com>
parents:
diff changeset
66 Operator files can be created either to add new variants of existing types of
510f744d0876 Add some documentation for the file format
Jonatan Werpers <jonatan@werpers.com>
parents:
diff changeset
67 operators like ``D_1`` or ``D_2`` or to describe completely new types of
510f744d0876 Add some documentation for the file format
Jonatan Werpers <jonatan@werpers.com>
parents:
diff changeset
68 operators like for example a novel kind of interpolation operator. In the
510f744d0876 Add some documentation for the file format
Jonatan Werpers <jonatan@werpers.com>
parents:
diff changeset
69 second case new parsing functions are also necessary.
510f744d0876 Add some documentation for the file format
Jonatan Werpers <jonatan@werpers.com>
parents:
diff changeset
70
510f744d0876 Add some documentation for the file format
Jonatan Werpers <jonatan@werpers.com>
parents:
diff changeset
71 The files can then be used to easily test or share different variants of
510f744d0876 Add some documentation for the file format
Jonatan Werpers <jonatan@werpers.com>
parents:
diff changeset
72 operators.