-
Notifications
You must be signed in to change notification settings - Fork 3
/
README_ENG
264 lines (207 loc) · 10.5 KB
/
README_ENG
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
------------------------------------------------------------------------------
| Collection of exact solutions (ColESo) |
| |
| Revised 21.06.2022 |
------------------------------------------------------------------------------
See the file COPYING for license information.
See the file AUTHORS for information about authors and contributors.
See the file NEWS for recent revisions.
I. Introduction
II. Directories and Files
III. Building of ColESo and running checks
IV. Usage
Usage with C++
Usage with C
Usage with FORTRAN
V. Format of parameters files
VI. Errors treatment
VII. Thread-safety
VIII. Used libraries
IX. Contacts
Introduction
------------
Collection of exact solutions (ColESo library) consists of more than
30 analytical solutions. The main purpose is the verification of
numerical methods for compressible flow simulation. The base of
the collection is a set of solutions of linearized Euler and
Navier – Stokes equations. Besides, ColESo incorporates several
nonlinear solutions, including the solution of Riemann problem.
Directories
-----------
There are seven directories in the main directory of this distribution,
described below
docs This directory contains documents related to ColESo library.
example This directory contains simple programs on FORTRAN, C, and C++
illustrating the usage of ColESo library.
projects This directory contains a solution for Microsoft Visual Studio 2008.
qd This directory contains QD library (quad-double/double-double
computation package). This package is not a part of ColESo library
and is given for the benefit of the user.
src This directory contains the source code of the ColESo library,
including tests and the C++ header files.
es_specfunc.cpp and es_specfunc_dd.cpp contains special functions.
es_jacobi_rule.hpp contains Gauss - Jacobi quadrature formulas.
es_aux.cpp implements outer interface.
es_tests.cpp contains some checks whether the solutions satisfy
the equations they should.
io_parser.cpp is a file and formula parser with square wheels.
Other *.cpp files implements one or more exact solutions.
templates For each solution implemented in ColESo, this directory contains
a file with the set of parameters. File format is described below.
test This directory contains examples of the use of ColESo library
that dumps data to plot figures. Examples are given in each
of the following languages: C++, C, and FORTRAN.
To plot figures using the generated data, bash script and gnuplot
are used.
Building of ColESo and running checks
-------------------------------------
Building is possible using Makefile. The description of targets is below.
All libraries and executables will be created in ./bin.
qd-package Build QD library
lib Build ColESo library with double precision only
libqd Build ColESo library with double, double-double and quad-double
precision
examplecpp Build a simple program on C++ that uses ColESo
examplec Build a simple program on C that uses ColESo
examplef Build a simple program on FORTRAN that uses ColESo
examplecppqd Build a simple program on C++ that uses ColESo with extra
precision
testcpp Build a program on C++ that dumps data needed to plot figures
testcpprun The same, and run it, and plot figures using gnuplot
testc Build a program on C that dumps data needed to plot figures
testcrun The same, and run it, and plot figures using gnuplot
testf Build a program on FORTRAN that dumps data needed to plot figures
testfrun The same, and run it, and plot figures using gnuplot
check Run checks that the solutions satisfy the equations they
should satisfy
checkqd For the solution for wave in a circular channel, check
the solution satisfies linearized Navier - Stokes equations
with double, double-double, and quad-double precision
clean Removes all output directories (bin, test/DATA1D, test/DATA2D)
For Microsoft Visual Studio users, we enclose a solution containing two simple
programs on C++, one of them uses double precision and another one uses
double-double precision. To build the second one, the user should define the
corresponding flag (#define EXTRAPRECISION_COLESO) in src/personal.h
and rebuild the ColESo library.
Usage
-----
In order to compute an exact solution using ColESo library, one should
proceed with the following operations.
1) Create an object corresponding to the solution in need.
2) Specify parameters of the solution or call the function reading them from file.
3) Call the function initializing the solution.
4) Call the function computing the solution at a point and a time moment given.
This function can be called multiple times, at single- or multiple-thread mode.
Usage with C++
--------------
In C++, one can directly handle the objects corresponging to exact solutions.
Each exact solution corresponds to a class inheriting abstract class tPointFunction.
I. Create an object.
To create an object corresponding to an exact solution one should create an instance
of the corresponding class. For example,
s_CornerPlanar S;
II. Specify parameters.
Parameters can be read from a file using method ReadParamsFromFile(const char*).
For example, to read parameters from file.txt one can write
S.ReadParamsFromFile("file.txt");
If file name is not specified, then default file name corresponding to the class
will be used. In this case, this is es_cornerplanar.txt.
Parameters can also be specified by direct assign to class members.
For example, to specify unit amplitude one can write
S.Aterm = 1.0;
Class members can slightly differ from the parameter names as they are read
from the file. This correspondence becomes clear once one look at the
code of the method ReadParams() of the corresponding class.
III. Initialize.
Prior to compute the solution, the solution should be initialized. For example,
S.Init();
IV. Compute the solution.
To compute the solution, one should use method PointValue. It takes time, coordinates,
and a pointer to the output array. Minimal size of the output array depends on
the solution type but not more than 10 elements.
Usage with C
------------
To be usable in programs written in C, ColESo library has the static
vector of objects accessible through a special interface.
I. Create an object.
To create an object corresponding to an exact solution one should call the function
void coleso_add_function(char* FUNCNAME, int* ID);
This function takes the name of a solution, creates an object and returns
its identifier (position in the vector). For example,
int ID; coleso_add_function("CornerPlanar", &ID);
Further access to the created object is provided via this identifier.
II. Specify parameters.
Parameters can be read from a file using function
void coleso_read_file(int ID, char* FILENAME);
This function takes an identifier and a name of a file. For example,
coleso_read_file(ID, "PARAMS/es_cornerplanar.txt");
Parameters can also be specified using string-based interface, namely,
void coleso_set_parameter(char* PARAMNAME, char* PARAMVALUE);
void coleso_read_set(int ID);
The first function adds a parameter to the static string buffer,
and the second one reads data from it similar to the reading from file.
Argument PARAMNAME coincides with the parameter name as it is written
in file and does not obligatory coincide with the name of the class member.
For example,
coleso_set_parameter("Aterm", "1.0");
coleso_set_parameter("Bterm", "3.0");
coleso_read_set(ID);
III. Initialize.
Prior to compute the solution, the solution should be initialized
using function
void coleso_init(int ID);
For example,
coleso_init(ID);
IV. Compute the solution.
To compute the solution, one should use the function
void coleso_pointvalue(int ID, double T, double* C, double* V);
It takes time, coordinates, and a pointer to the output array.
Minimal size of the output array depends on
the solution type but not more than 10 elements.
Usage with FORTRAN
------------------
The use of ColESo in FORTRAN is similar to its use in C.
Note that each string passing to ColESo should be NULL-terminated
for the correct treatment in C/C++.
An example of the use of ColESo in a program in FORTRAN
can be found in example.f.
Parameters file format
----------------------
Parameters file is read line-by-line. Each line consists of a parameter name
and its value separated by spaces and/or tabs.
Value is an arithmetic expression, where constant PI is defined.
Starting from '#', all symbols in a line are ignored.
Byte Order Mark (BOM) in the beginning of a file is unacceptable.
In templates folder, some parameters are commented, i. e. disabled by placing
'#' in the beginning of the line. This is for the benifit of the author.
To use these parameters, symbol '#' should be removed.
Error treatment
---------------
In a case of error, ColESo does not return an error code to the calling subroutine.
It executes the macro crash(...) defined in personal.h. It can be redefined.
In reading the parameters file and in some Init() subroutines,
log is processing using the macro pprintf(...), which can also be redefined.
Thread-safety
-------------
ColESo library itself is thread-safe.
Interface for C and FORTRAN programs is based on static variables.
When calling coleso_add_function, there must be no other access
to ColESo at the same time. When specifying parameters of a solution,
parameters of another solutions must not be specified.
Used libraries
--------------
ColESo uses several auxiliary functions from open source projects, including:
* Cephes, http://www.netlib.org/cephes (distributable under MIT license)
* GNU LibQuadMath, https://gcc.gnu.org/onlinedocs/gcc-4.9.4/libquadmath
(distributable under GPL v2.1 licence)
* Jacobi quadrature rules by S. Elhay, J. Kautsky, J. Burkadrt,
people.sc.fsu.edu/~jburkardt/cpp_src/jacobi_rule/jacobi_rule.html
(distributable under LGPL licence)
In order to deal with extra precision floating point arithmetics,
ColESo uses the following library:
* QD – A C++/Fortran-90 double-double and quad-double package,
https://github.com/aoki-t/QD
Contacts
--------
In case you have question regarding ColESo, want to report bugs
or contribute to the project you can use the mail box <bahvalo@mail.ru>.