Mercurial > repos > public > sbplib_julia

annotate docs/src/operator_file_format.md @ 877:dd2ab001a7b6 feature/equidistant_grid/refine

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Implement refine function, move exports to the top of the file, change location of constuctors. The constructors were changed have only one inner constructor and simpler outer constructors.
author Jonatan Werpers <jonatan@werpers.com>
date Mon, 14 Feb 2022 09:39:58 +0100
parents fe8fe3f01162
children 7bf3121c6864
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
510f744d0876 Add some documentation for the file format
Jonatan Werpers <jonatan@werpers.com>
parents:
diff changeset
19 * [`read_stencil_set`](@ref)
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.