Mercurial > repos > public > sbplib_julia

comparison src/SbpOperators/readoperator.jl @ 835:fc2ac236dd73 operator_storage_array_of_table

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Add a bunch of documentation
author Jonatan Werpers <jonatan@werpers.com>
date Thu, 13 Jan 2022 09:14:36 +0100
parents 760c11e81fd4
children 91a63b04b1c9
comparison
equal deleted inserted replaced
834:a8d64785f51b 835:fc2ac236dd73
7 export parse_scalar 7 export parse_scalar
8 export parse_tuple 8 export parse_tuple
9 9
10 export sbp_operators_path 10 export sbp_operators_path
11 11
12 # The read_stencil_set and get_stencil_set functions return the freshly parsed 12 # TODO: Think about naming and terminology around freshly parsed TOML. answer: toml_dict/parsed_toml?
13 # toml. The generic code in these functions can't be expected to know anyhting
14 # about how to read different stencil sets as they may contain many different
15 # kinds of stencils. We should how ever add read_ and get_ functions for all
16 # the types of stencils we know about.
17 #
18 # After getting a stencil set the user can use parse functions to parse what
19 # they want from the TOML dict. I.e no more "paths".
20 # Functions needed:
21 # * parse stencil
22 # * parse rational
23 #
24 # maybe there is a better name than parse?
25 # Would be nice to be able to control the type in the stencil
26
27 # TODO: Control type for the stencil
28 # TODO: Think about naming and terminology around freshly parsed TOML.
29 # Vidar: What about get_stencil instead of parse_stencil for an already parsed
30 # toml. It matches get_stencil_set.
31 13
32 # TODO: Docs for readoperator.jl 14 # TODO: Docs for readoperator.jl
33 # Parsing as rationals is intentional, allows preserving exactness, which can be lowered using converts or promotions later. 15 # Parsing as rationals is intentional, allows preserving exactness, which can be lowered using converts or promotions later.
34 # TODO: readoperator.jl file name? 16 # Documetning the format: Allows representing rationals as strings
35 # TODO: Remove references to toml for dict-input arguments 17 # TODO: Remove references to toml for dict-input arguments
36 # TODO: Documetning the format: Allows representing rationals as strings
37 18
38 """ 19 """
39 read_stencil_set(fn; filters) 20 read_stencil_set(fn; filters)
40 21
41 Picks out a stencil set from the given toml file based on some filters. 22 Picks out a stencil set from the given toml file based on some key-value filters.
42 If more than one set matches the filters an error is raised. 23 If more than one set matches the filters an error is raised.
43 24
44 The stencil set is not parsed beyond the inital toml parse. To get usable 25 The stencil set is not parsed beyond the inital toml parse. To get usable
45 stencils use the `parse_stencil` functions on the fields of the stencil set. 26 stencils use the `parse_stencil` functions on the fields of the stencil set.
27
28 The reason for this is that since stencil sets are intended to be very
29 general, and currently do not include any way to specify how to parse a given
30 section, the exact parsing is left to the user.
31
32 See also [`sbp_operators_path`](@ref), [`get_stencil_set`](@ref), [`parse_stencil`](@ref), [`parse_scalar`](@ref), [`parse_tuple`](@ref),.
46 """ 33 """
47 read_stencil_set(fn; filters...) = get_stencil_set(TOML.parsefile(fn); filters...) 34 read_stencil_set(fn; filters...) = get_stencil_set(TOML.parsefile(fn); filters...)
48 35
49 """ 36 """
50 get_stencil_set(parsed_toml; filters...) 37 get_stencil_set(parsed_toml; filters...)
51 38
52 Same as `read_stencil_set` but works on already parsed TOML. 39 Same as `read_stencil_set` but works on already parsed TOML.
40
41 See also [`read_stencil_set`](@ref).
53 """ 42 """
54 function get_stencil_set(parsed_toml; filters...) 43 function get_stencil_set(parsed_toml; filters...)
55 matches = findall(parsed_toml["stencil_set"]) do set 44 matches = findall(parsed_toml["stencil_set"]) do set
56 for (key, val) ∈ filters 45 for (key, val) ∈ filters
57 if set[string(key)] != val 46 if set[string(key)] != val
72 61
73 """ 62 """
74 parse_stencil(toml) 63 parse_stencil(toml)
75 64
76 Accepts parsed toml and reads it as a stencil 65 Accepts parsed toml and reads it as a stencil
66
67 See also [`read_stencil_set`](@ref), [`parse_scalar`](@ref), [`parse_tuple`](@ref).
77 """ 68 """
78 function parse_stencil(toml) 69 function parse_stencil(toml)
79 check_stencil_toml(toml) 70 check_stencil_toml(toml)
80 71
81 if toml isa Array 72 if toml isa Array
85 76
86 weights = parse_rational.(toml["s"]) 77 weights = parse_rational.(toml["s"])
87 return Stencil(weights..., center = toml["c"]) 78 return Stencil(weights..., center = toml["c"])
88 end 79 end
89 80
81 """
82 parse_stencil(T, toml)
83
84 Parses the stencil with element type `T`
85 """
90 parse_stencil(T, toml) = Stencil{T}(parse_stencil(toml)) 86 parse_stencil(T, toml) = Stencil{T}(parse_stencil(toml))
91 87
92 function check_stencil_toml(toml) 88 function check_stencil_toml(toml)
93 if !(toml isa Dict || toml isa Vector{String}) 89 if !(toml isa Dict || toml isa Vector{String})
94 throw(ArgumentError("the TOML for a stencil must be a vector of strings or a table.")) 90 throw(ArgumentError("the TOML for a stencil must be a vector of strings or a table."))
109 if !(toml["c"] isa Int) 105 if !(toml["c"] isa Int)
110 throw(ArgumentError("the center of a stencil must be specified as an integer.")) 106 throw(ArgumentError("the center of a stencil must be specified as an integer."))
111 end 107 end
112 end 108 end
113 109
110 """
111 parse_scalar(toml)
114 112
113 Parse a scalar, represented as a string or a number in the TOML, and return it as a `Rational`
114
115 See also [`read_stencil_set`](@ref), [`parse_stencil`](@ref) [`parse_tuple`](@ref).
116 """
115 function parse_scalar(toml) 117 function parse_scalar(toml)
116 try 118 try
117 return parse_rational(toml) 119 return parse_rational(toml)
118 catch e 120 catch e
119 throw(ArgumentError("must be a number or a string representing a number.")) 121 throw(ArgumentError("must be a number or a string representing a number."))
120 end 122 end
121 end 123 end
122 124
125 """
126 parse_tuple(toml)
127
128 Parse `toml` as a tuple of scalars.
129
130 See also [`read_stencil_set`](@ref), [`parse_stencil`](@ref), [`parse_scalar`](@ref).
131 """
123 function parse_tuple(toml) 132 function parse_tuple(toml)
124 if !(toml isa Array) 133 if !(toml isa Array)
125 throw(ArgumentError("argument must be an array")) 134 throw(ArgumentError("argument must be an array"))
126 end 135 end
127 return Tuple(parse_scalar.(toml)) 136 return Tuple(parse_scalar.(toml))
128 end 137 end
129 138
139
140 """
141 parse_rational(toml)
142
143 Parse a string or a number as a rational.
144 """
130 function parse_rational(toml) 145 function parse_rational(toml)
131 if toml isa String 146 if toml isa String
132 expr = Meta.parse(replace(toml, "/"=>"//")) 147 expr = Meta.parse(replace(toml, "/"=>"//"))
133 return eval(:(Rational($expr))) 148 return eval(:(Rational($expr)))
134 else 149 else
135 return Rational(toml) 150 return Rational(toml)
136 end 151 end
137 end 152 end
138 153
154 """
155 sbp_operators_path()
156
157 Calculate the path for the operators folder with included stencil sets.
158
159 See also [`read_stencil_set`](@ref)
160 """
139 sbp_operators_path() = (@__DIR__) * "/operators/" 161 sbp_operators_path() = (@__DIR__) * "/operators/"