Mercurial > repos > public > sbplib_julia

comparison docs/src/operator_file_format.md @ 852:510f744d0876 operator_storage_array_of_table

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