/[escript]/trunk/escriptcore/src/escriptcpp.cpp
ViewVC logotype

Contents of /trunk/escriptcore/src/escriptcpp.cpp

Parent Directory Parent Directory | Revision Log Revision Log


Revision 6336 - (show annotations)
Fri Jul 1 12:37:05 2016 UTC (2 years, 2 months ago) by caltinay
File size: 76608 byte(s)
(3) add isComplex & setComplex to solver options.

1
2 /*****************************************************************************
3 *
4 * Copyright (c) 2003-2016 by The University of Queensland
5 * http://www.uq.edu.au
6 *
7 * Primary Business: Queensland, Australia
8 * Licensed under the Apache License, version 2.0
9 * http://www.apache.org/licenses/LICENSE-2.0
10 *
11 * Development until 2012 by Earth Systems Science Computational Center (ESSCC)
12 * Development 2012-2013 by School of Earth Sciences
13 * Development from 2014 by Centre for Geoscience Computing (GeoComp)
14 *
15 *****************************************************************************/
16
17 #include "AbstractContinuousDomain.h"
18 #include "AbstractReducer.h"
19 #include "AbstractSystemMatrix.h"
20 #include "AbstractTransportProblem.h"
21 #include "Data.h"
22 #include "DataFactory.h"
23 #include "DataVector.h"
24 #include "EscriptParams.h"
25 #include "ExceptionTranslators.h"
26 #include "FunctionSpace.h"
27 #include "FunctionSpaceFactory.h"
28 #include "MPIDataReducer.h"
29 #include "MPIScalarReducer.h"
30 #include "NonReducedVariable.h"
31 #include "SolverOptions.h"
32 #include "SplitWorld.h"
33 #include "SubWorld.h"
34 #include "TestDomain.h"
35 #include "Utils.h"
36
37 #include <boost/python.hpp>
38 #include <boost/python/def.hpp>
39 #include <boost/python/errors.hpp>
40 #include <boost/python/module.hpp>
41 #include <boost/python/object.hpp>
42 #include <boost/python/tuple.hpp>
43 #include <boost/smart_ptr.hpp>
44 #include <boost/version.hpp>
45
46 using namespace boost::python;
47
48 /*! \mainpage Esys Documentation
49 *
50 * \version 4.2
51 *
52 * Main modules/namespaces:
53 *
54 * - \ref escript
55 *
56 * - \ref paso
57 *
58 * - \ref finley
59 *
60 * - \ref dudley
61 *
62 * - \ref ripley
63 *
64 * - \ref speckley
65 *
66 * - \ref weipa
67 *
68 * This documentation describes the C++ layer of escript and related libraries.
69 * For documentation of the python API, please see:
70 * <a href="../../sphinx_api/index.html">Here</a>
71 *
72 */
73
74 #include <boost/python/raw_function.hpp>
75
76 namespace
77 {
78
79 bool block_cmp_data(const escript::Data&, boost::python::object o)
80 {
81 PyErr_SetString(PyExc_TypeError,"Python relational operators are not defined for Data objects.");
82 boost::python::throw_error_already_set();
83 return false;
84 }
85
86
87 bool block_eq_data(const escript::Data&, boost::python::object o)
88 {
89 PyErr_SetString(PyExc_TypeError,"The Python == and != operators are not defined for Data objects. "
90 "To check for object identity use 'is'. To check for numerical similarity of x and y, use Lsup(x-y)<TOL "
91 "for a suitable tolerance.");
92 boost::python::throw_error_already_set();
93 return false;
94 }
95
96 bool block_cmp_functionspace(const escript::FunctionSpace&, boost::python::object o)
97 {
98 PyErr_SetString(PyExc_TypeError,"Python relational operators are not defined for FunctionSpaces.");
99 boost::python::throw_error_already_set();
100 return false;
101 }
102
103 bool block_cmp_domains(const escript::AbstractDomain&, boost::python::object o)
104 {
105 PyErr_SetString(PyExc_TypeError,"Python relational operators are not defined for Domains.");
106 boost::python::throw_error_already_set();
107 return false;
108 }
109 }
110
111 BOOST_PYTHON_MODULE(escriptcpp)
112 {
113 #if BOOST_VERSION >= 103500
114 // params are: bool show_user_defined, bool show_py_signatures, bool show_cpp_signatures
115 docstring_options docopt(true,true,false);
116 #endif
117
118 scope().attr("__doc__") = "To use this module, please import esys.escript";
119
120 // register escript's default translators
121 REGISTER_ESCRIPT_EXCEPTION_TRANSLATORS;
122
123 /* begin SubWorld things */
124
125 class_<escript::AbstractReducer, escript::Reducer_ptr, boost::noncopyable>("Reducer", "", no_init);
126
127 // Why doesn't this have a doc-string? Because it doesn't compile if you try to add one
128 // These functions take a SplitWorld instance as their first parameter
129 def("internal_buildDomains", raw_function(escript::raw_buildDomains,2));
130 def("internal_addJob", raw_function(escript::raw_addJob,2));
131 def("internal_addJobPerWorld", raw_function(escript::raw_addJobPerWorld,2));
132 def("internal_addVariable", raw_function(escript::raw_addVariable,3));
133
134
135 def("internal_makeDataReducer", escript::makeDataReducer, arg("op"), "Create a reducer to work with Data and the specified operation.");
136 def("internal_makeScalarReducer", escript::makeScalarReducer, arg("op"), "Create a reducer to work with doubles and the specified operation.");
137 def("internal_makeLocalOnly", escript::makeNonReducedVariable, "Create a variable which is not connected to copies in other worlds.");
138
139 class_<escript::SplitWorld, boost::noncopyable>("Internal_SplitWorld", "Manages a group of sub worlds. For internal use only.", init<unsigned int>(args("num_worlds")))
140 .def("runJobs", &escript::SplitWorld::runJobs, "Execute pending jobs.")
141 .def("removeVariable", &escript::SplitWorld::removeVariable, arg("name"), "Remove the named variable from the SplitWorld")
142 .def("clearVariable", &escript::SplitWorld::clearVariable, arg("name"), "Remove the value from the named variable")
143 .def("getVarList", &escript::SplitWorld::getVarPyList, "Lists variables known to the system")
144 .def("getVarInfo", &escript::SplitWorld::getVarPyInfo, "Lists variable descriptions known to the system")
145 .def("getDoubleVariable", &escript::SplitWorld::getScalarVariable, "Return the value of floating point variable")
146 .def("getLocalObjectVariable", &escript::SplitWorld::getLocalObjectVariable, "Returns python object for a variable which is not shared between worlds")
147 .def("getSubWorldCount",&escript::SplitWorld::getSubWorldCount)
148 .def("getSubWorldID", &escript::SplitWorld::getSubWorldID)
149 .def("copyVariable", &escript::SplitWorld::copyVariable, args("source","destination"), "Copy the contents of one variable to another");
150
151 // This class has no methods. This is deliberate - at this stage, I would like this to be an opaque type
152 class_ <escript::SubWorld, escript::SubWorld_ptr, boost::noncopyable>("SubWorld", "Information about a group of workers.", no_init);
153 /* end SubWorld things */
154
155 def("setNumberOfThreads",escript::setNumberOfThreads,"Use of this method is strongly discouraged.");
156 def("getNumberOfThreads",escript::getNumberOfThreads,"Return the maximum number of threads"
157 " available to OpenMP.");
158 def("releaseUnusedMemory",escript::DataTypes::releaseUnusedMemory);
159 def("getVersion",escript::getSvnVersion,"This method will only report accurate version numbers for clean checkouts.");
160 def("printParallelThreadCounts",escript::printParallelThreadCnt);
161 def("getMPISizeWorld",escript::getMPISizeWorld,"Return number of MPI processes in the job.");
162 def("getMPIRankWorld",escript::getMPIRankWorld,"Return the rank of this process in the MPI World.");
163 def("MPIBarrierWorld",escript::MPIBarrierWorld,"Wait until all MPI processes have reached this point.");
164 def("getMPIWorldMax",escript::getMPIWorldMax,"\n"
165 "Each MPI process calls this function with a"
166 " value for arg1. The maximum value is computed and returned.\n\n"
167 ":rtype: int");
168 def("getMPIWorldSum",escript::getMPIWorldSum,"\n"
169 "Each MPI process calls this function with a"
170 " value for arg1. The values are added up and the total value is returned.\n\n"
171 ":rtype: int");
172 def("runMPIProgram",escript::runMPIProgram,"Spawns an external MPI program using a separate communicator.");
173 def("getMachinePrecision",escript::getMachinePrecision);
174 def("getMaxFloat",escript::getMaxFloat);
175 def("_saveDataCSV",escript::saveDataCSV, (args("filename","arg","sep","csep"), arg("append")=false),
176 "Saves data objects passed in a python dictionary to a file.\n"
177 "The data objects must be over the same domain and be able to be interpolated to the same FunctionSpace.\n"
178 "If one of the dictionary keys is named ``mask``, then only samples where ``mask`` has a positive\n"
179 "value will be written to the file.\n\n"
180 "A header line giving the names of each column will be output first.\n"
181 "The keys given in the dictionary will be used to name columns.\n"
182 "Then the data will be output, one line per sample (for all data).\n"
183 "That is, items in each column will be printed in the same order.\n"
184 "So you can be sure that values in the same row correspond to the same input value.\n\n"
185 "\n"
186 ":param filename:\n"
187 ":type filename: ``string``\n"
188 ":param arg: dictionary of named `Data` objects. If one is called ``mask`` it must be scalar data.\n"
189 ":type arg: ``dict``\n"
190 ":param sep: separator for columns (defaults to ',')\n"
191 ":type sep: ``string``\n"
192 ":param csep: separator for fields within data object (defaults to \"_\")\n"
193 ":type csep: ``string``\n"
194 ":param append: If True, write to the end of ``filename``\n"
195 ":type append: ``string``\n"
196 "");
197 def("canInterpolate", &escript::canInterpolate, args("src", "dest"),":param src: Source FunctionSpace\n"
198 ":param dest: Destination FunctionSpace\n"
199 ":return: True if src can be interpolated to dest\n"
200 ":rtype: `bool`");
201
202 //
203 // Interface for AbstractDomain
204 //
205 class_<escript::AbstractDomain, escript::Domain_ptr, boost::noncopyable >("Domain","Base class for all domains.",no_init)
206 .def("getStatus",&escript::AbstractDomain::getStatus,"The status of a domain changes whenever the domain is modified\n\n"
207 ":rtype: int")
208 .def("setTagMap",&escript::AbstractDomain::setTagMap,args("name","tag"),
209 "Give a tag number a name.\n\n"
210 ":param name: Name for the tag\n"
211 ":type name: ``string``\n"
212 ":param tag: numeric id\n"
213 ":type tag: ``int``\n"
214 ":note: Tag names must be unique within a domain")
215 .def("getTag",&escript::AbstractDomain::getTag,args("name"),":return: tag id for "
216 "``name``\n"
217 ":rtype: ``string``")
218 .def("isValidTagName",&escript::AbstractDomain::isValidTagName,args("name"),
219 ":return: True is ``name`` corresponds to a tag\n"
220 ":rtype: ``bool``")
221 .def("showTagNames",&escript::AbstractDomain::showTagNames,":return: A space separated list of tag names\n"
222 ":rtype: ``string``")
223 .def("getX",&escript::AbstractDomain::getX,":rtype: `Data`\n"
224 ":return: Locations in the"
225 "`Domain`. FunctionSpace is chosen appropriately")
226 .def("getDim",&escript::AbstractDomain::getDim,":rtype: `int`\n"
227 ":return: Spatial dimension of the `Domain`")
228 .def("getNormal",&escript::AbstractDomain::getNormal,":rtype: `escript`\n"
229 ":return: Boundary normals")
230 .def("getSize",&escript::AbstractDomain::getSize,":return: the local size of samples. The function space is chosen appropriately\n"
231 ":rtype: `Data`")
232 .def("dump",&escript::AbstractDomain::dump,args("filename"),"Dumps the domain to a file\n\n"
233 ":param filename: \n"
234 ":type filename: string")
235 .def("getMPISize",&escript::AbstractDomain::getMPISize,":return: the number of processes used for this `Domain`\n"
236 ":rtype: ``int``")
237 .def("getMPIRank",&escript::AbstractDomain::getMPIRank,":return: the rank of this process\n"
238 ":rtype: ``int``")
239 .def("MPIBarrier",&escript::AbstractDomain::MPIBarrier,"Wait until all processes have reached this point")
240 .def("onMasterProcessor",&escript::AbstractDomain::onMasterProcessor,":return: True if this code is executing on the master process\n"
241 ":rtype: `bool`")
242 .def("supportsContactElements", &escript::AbstractDomain::supportsContactElements,"Does this domain support contact elements.")
243 .def(self == self)
244 .def(self != self)
245 .def("__lt__", block_cmp_domains)
246 .def("__le__", block_cmp_domains)
247 .def("__gt__", block_cmp_domains)
248 .def("__ge__", block_cmp_domains);
249
250 //
251 // Interface for AbstractContinuousDomain
252 //
253 class_<escript::AbstractContinuousDomain, bases<escript::AbstractDomain>, boost::noncopyable >("ContinuousDomain","Class representing continuous domains",no_init)
254 .def("getSystemMatrixTypeId", &escript::AbstractContinuousDomain::getSystemMatrixTypeId,
255 args("options"),
256 ":return: the identifier of the matrix type to be used for the global stiffness matrix "
257 "when particular solver options are used.\n"
258 ":rtype: int")
259 .def("getTransportTypeId",&escript::AbstractContinuousDomain::getTransportTypeId,
260 args("solver", "preconditioner", "package", "symmetry"))
261
262 .def("addPDEToSystem",&escript::AbstractContinuousDomain::addPDEToSystem,
263 args("mat", "rhs","A", "B", "C", "D", "X", "Y", "d", "y", "d_contact", "y_contact", "d_dirac", "y_dirac"),
264 "adds a PDE onto the stiffness matrix mat and a rhs\n\n"
265 ":param mat:\n"
266 ":type mat: `OperatorAdapter`\n"
267 ":param rhs:\n"
268 ":type rhs: `Data`\n"
269 ":param A:\n"
270 ":type A: `Data`\n"
271 ":param B:\n"
272 ":type B: `Data`\n"
273 ":param C:\n"
274 ":type C: `Data`\n"
275 ":param D:\n"
276 ":type D: `Data`\n"
277 ":param X:\n"
278 ":type X: `Data`\n"
279 ":param Y:\n"
280 ":type Y: `Data`\n"
281 ":param d:\n"
282 ":type d: `Data`\n"
283 ":param d_contact:\n"
284 ":type d_contact: `Data`\n"
285 ":param y_contact:\n"
286 ":type y_contact: `Data`\n"
287 ":param d_dirac:\n"
288 ":type d_dirac: `Data`\n"
289 ":param y_dirac:\n"
290 ":type y_dirac: `Data`\n"
291 )
292 .def("addPDEToRHS",&escript::AbstractContinuousDomain::addPDEToRHS,
293 args("rhs", "X", "Y", "y", "y_contact", "y_dirac"),
294 "adds a PDE onto the stiffness matrix mat and a rhs\n\n"
295 ":param rhs:\n"
296 ":type rhs: `Data`\n"
297 ":param X:\n"
298 ":type X: `Data`\n"
299 ":param Y:\n"
300 ":type Y: `Data`\n"
301 ":param y:\n"
302 ":type y: `Data`\n"
303 ":param y_contact:\n"
304 ":type y_contact: `Data`\n"
305 ":param y_dirac:\n"
306 ":type y_dirac: `Data`"
307 )
308 .def("addPDEToTransportProblem",&escript::AbstractContinuousDomain::addPDEToTransportProblem,
309 args( "tp", "source", "M", "A", "B", "C", "D", "X", "Y", "d", "y", "d_contact", "y_contact", "d_dirac", "y_dirac"),
310 ":param tp:\n"
311 ":type tp: `TransportProblemAdapter`\n"
312 ":param source:\n"
313 ":type source: `Data`\n"
314 ":param M:\n"
315 ":type M: `Data`\n"
316 ":param A:\n"
317 ":type A: `Data`\n"
318 ":param B:\n"
319 ":type B: `Data`\n"
320 ":param C:\n"
321 ":type C: `Data`\n"
322 ":param D:\n"
323 ":type D: `Data`\n"
324 ":param X:\n"
325 ":type X: `Data`\n"
326 ":param Y:\n"
327 ":type Y: `Data`\n"
328 ":param d:\n"
329 ":type d: `Data`\n"
330 ":param y:\n"
331 ":type y: `Data`\n"
332 ":param d_contact:\n"
333 ":type d_contact: `Data`\n"
334 ":param y_contact:\n"
335 ":type y_contact: `Data`\n"
336 ":param d_dirac:\n"
337 ":type d_dirac: `Data`\n"
338 ":param y_dirac:\n"
339 ":type y_dirac: `Data`\n"
340 )
341 .def("newOperator",&escript::AbstractContinuousDomain::newSystemMatrix,
342 args("row_blocksize", "row_functionspace", "column_blocksize", "column_functionspace", "type"),
343 "creates a SystemMatrixAdapter stiffness matrix and initializes it with zeros\n\n"
344 ":param row_blocksize:\n"
345 ":type row_blocksize: ``int``\n"
346 ":param row_functionspace:\n"
347 ":type row_functionspace: `FunctionSpace`\n"
348 ":param column_blocksize:\n"
349 ":type column_blocksize: ``int``\n"
350 ":param column_functionspace:\n"
351 ":type column_functionspace: `FunctionSpace`\n"
352 ":param type:\n"
353 ":type type: ``int``\n"
354 )
355 .def("newTransportProblem",&escript::AbstractContinuousDomain::newTransportProblem,
356 args("theta", "blocksize", "functionspace", "type"),
357 "creates a TransportProblemAdapter\n\n"
358 ":param theta:\n"
359 ":type theta: ``float``\n"
360 ":param blocksize:\n"
361 ":type blocksize: ``int``\n"
362 ":param functionspace:\n"
363 ":type functionspace: `FunctionSpace`\n"
364 ":param type:\n"
365 ":type type: ``int``\n"
366 )
367 .def("getDataShape",&escript::AbstractContinuousDomain::getDataShape, args("functionSpaceCode"),
368 ":return: a pair (dps, ns) where dps=the number of data points per sample, and ns=the number of samples\n"
369 ":rtype: ``tuple``")
370 .def("print_mesh_info",&escript::AbstractContinuousDomain::Print_Mesh_Info,(arg("full")=false),
371 ":param full:\n"
372 ":type full: ``bool``")
373 .def("getDescription",&escript::AbstractContinuousDomain::getDescription,
374 ":return: a description for this domain\n"
375 ":rtype: ``string``")
376 .def("setX",&escript::AbstractContinuousDomain::setNewX,
377 args("arg"), "assigns new location to the domain\n\n"
378 ":param arg:\n"
379 ":type arg: `Data`")
380 .def("getNumDataPointsGlobal",&escript::AbstractContinuousDomain::getNumDataPointsGlobal,
381 ":return: the number of data points summed across all MPI processes\n"
382 ":rtype: ``int``");
383
384
385
386
387 //
388 // Interface for TestDomain
389 //
390 class_ <escript::TestDomain, bases<escript::AbstractDomain> >("TestDomain",
391 "Test Class for domains with no structure. May be removed from future releases without notice.", no_init);
392
393 // This is the only python visible way to get a TestDomain
394 def("getTestDomainFunctionSpace",&escript::getTestDomainFunctionSpace, (arg("dpps"),
395 arg("samples"), arg("size")=1),
396 "For testing only. May be removed without notice.");
397
398 //
399 // Interface for FunctionSpace
400 //
401 class_<escript::FunctionSpace> fs_definer("FunctionSpace","A FunctionSpace describes which points from the `Domain` to use to represent functions.",init<>()); // Doco goes in the empty string param
402 fs_definer.def("getDim",&escript::FunctionSpace::getDim,":return: the spatial dimension of the underlying domain.\n"
403 ":rtype: int");
404 // fs_definer.def("getDomain",&escript::FunctionSpace::getDomain,
405 // return_internal_reference<>());
406 fs_definer.def("getDomain",&escript::FunctionSpace::getDomainPython,":return: the underlying `Domain` for this FunctionSpace.\n"
407 ":rtype: `Domain`");
408 fs_definer.def("getX",&escript::FunctionSpace::getX,"\n"
409 ":return: a function whose values are its input coordinates. ie an identity function.\n"
410 ":rtype: `Data`");
411 fs_definer.def("getNormal",&escript::FunctionSpace::getNormal,":return: the surface normal field.\n\n"
412 ":rtype: `Data`");
413 fs_definer.def("getSize",&escript::FunctionSpace::getSize,":return: sample size\n"
414 ":rtype: `Data`");
415 fs_definer.def("setTags",&escript::FunctionSpace::setTags,args("newtag","mask"),
416 "Set tags according to a mask\n\n"
417 ":param newtag: tag number to set\n"
418 ":type newtag: string, non-zero ``int``\n"
419 ":param mask: Samples which correspond to positive values in the mask will be set to ``newtag``.\n"
420 ":type mask: scalar `Data`");
421 fs_definer.def("setTags",&escript::FunctionSpace::setTagsByString,args("newtag","mask"));
422 fs_definer.def("getTagFromDataPointNo",
423 &escript::FunctionSpace::getTagFromDataPointNo,":return: the tag associated with the given sample number.\n"
424 ":rtype: int");
425 fs_definer.def("getReferenceIDFromDataPointNo", &escript::FunctionSpace::getReferenceIDFromDataPointNo,args("dataPointNo"),":return: the reference number associated with ``dataPointNo``\n"
426 ":rtype: int ");
427 fs_definer.def("getListOfTags",&escript::FunctionSpace::getListOfTags,":return: a list of the tags used in this function space\n"
428 ":rtype: ``list``");
429 fs_definer.def("getApproximationOrder", &escript::FunctionSpace::getApproximationOrder,":return: the approximation order referring to the maximum degree of a polynomial which can be represented exactly in interpolation and/or integration.\n"
430 ":rtype: ``int``");
431 fs_definer.def("__str__", &escript::FunctionSpace::toString);
432 fs_definer.def("__lt__",block_cmp_functionspace);
433 fs_definer.def("__le__",block_cmp_functionspace);
434 fs_definer.def("__gt__",block_cmp_functionspace);
435 fs_definer.def("__ge__",block_cmp_functionspace);
436 fs_definer.def(self == self);
437 fs_definer.def(self != self);
438
439
440
441 //
442 // Interface for Data
443 //
444 class_<escript::Data>("Data"/*,shared_ptr<Data>*/, "Represents a collection of datapoints. It is used to store the values of a function. For more details please consult the c++ class documentation.",init<>())
445 // various constructors for Data objects
446 .def(init<object, optional<object, object, object>>(args("value", "p2", "p3", "p4")))
447 // Note for Lutz, Need to specify the call policy in order to return a
448 // reference. In this case return_internal_reference.
449 .def("__str__",&escript::Data::toString)
450 .def("getDomain",&escript::Data::getDomainPython,":rtype: `Domain`")
451 .def("getFunctionSpace",&escript::Data::getFunctionSpace,return_value_policy<copy_const_reference>(),":rtype: `FunctionSpace`")
452 .def("isEmpty",&escript::Data::isEmpty,"Is this object an instance of ``DataEmpty``\n\n"
453 ":rtype: ``bool``\n"
454 ":note: This is not the same thing as asking if the object contains datapoints.")
455 .def("isProtected",&escript::Data::isProtected,"Can this instance be modified.\n"
456 ":rtype: ``bool``")
457 .def("setProtection",&escript::Data::setProtection,"Disallow modifications to this data object\n\n"
458 ":note: This method does not allow you to undo protection.")
459 .def("getShape",&escript::Data::getShapeTuple,"\n"
460 "Returns the shape of the datapoints in this object as a python tuple. Scalar data has the shape ``()``\n\n"
461 ":rtype: ``tuple``")
462 .def("getRank",&escript::Data::getDataPointRank,":return: the number of indices required to address a component of a datapoint\n"
463 ":rtype: positive ``int``")
464 .def("dump",&escript::Data::dump,args("fileName"),"Save the data as a netCDF file\n\n"
465 ":param fileName: \n"
466 ":type fileName: ``string``")
467 .def("toListOfTuples",&escript::Data::toListOfTuples, (arg("scalarastuple")=false),
468 "Return the datapoints of this object in a list. Each datapoint is stored as a tuple.\n\n"
469 ":param scalarastuple: if True, scalar data will be wrapped as a tuple."
470 " True => [(0), (1), (2)]; False => [0, 1, 2]")
471 .def("copyWithMask",&escript::Data::copyWithMask,args("other","mask"),
472 "Selectively copy values from ``other`` `Data`."
473 "Datapoints which correspond to positive values in ``mask`` will be copied from ``other``\n"
474 "\n"
475 ":param other: source of values\n"
476 ":type other: `Data`\n"
477 ":param mask:\n"
478 ":type mask: Scalar `Data`")
479 .def("setTaggedValue",&escript::Data::setTaggedValue,args("tagKey","value"),
480 "Set the value of tagged Data.\n\n"
481 ":param tagKey: tag to update\n"
482 ":type tagKey: ``int``\n"
483 "")
484 .def("setTaggedValue",&escript::Data::setTaggedValueByName,args("name","value"),":param name: tag to update\n"
485 ":type name: ``string``\n"
486 ":param value: value to set tagged data to\n"
487 ":type value: ``object`` which acts like an array, ``tuple`` or ``list``\n"
488 "")
489 .def("getNumberOfDataPoints",&escript::Data::getNumDataPoints,":rtype: ``int``\n"
490 ":return: Number of datapoints in the object")
491 .def("isExpanded",&escript::Data::isExpanded,":rtype: ``bool``\n"
492 ":return: True if this ``Data`` is expanded.")
493 .def("isTagged",&escript::Data::isTagged,":rtype: ``bool``\n"
494 ":return: True if this ``Data`` is expanded.")
495 .def("isConstant",&escript::Data::isConstant,":rtype: ``bool``\n"
496 ":return: True if this ``Data`` is an instance of ``DataConstant``\n"
497 ":note: This does not mean the data is immutable.")
498 .def("isLazy",&escript::Data::isLazy,":rtype: ``bool``\n"
499 ":return: True if this ``Data`` is lazy.")
500 .def("isReady",&escript::Data::isReady,":rtype: ``bool``\n"
501 ":return: True if this ``Data`` is not lazy.")
502 .def("isComplex", &escript::Data::isComplex,":rtype: ``bool``\n"
503 ":return: True if this ``Data`` stores complex values.")
504 .def("expand",&escript::Data::expand,"Convert the data to expanded representation if it is not expanded already.")
505 .def("hasNaN",&escript::Data::hasNaN,"Returns return true if data contains NaN.")
506 .def("replaceNaN",&escript::Data::replaceNaNPython,args("value"),"Replaces NaN values with value")
507 .def("tag",&escript::Data::tag,"Convert data to tagged representation if it is not already tagged or expanded")
508 .def("resolve",&escript::Data::resolve,"Convert the data to non-lazy representation.")
509 .def("copy",&escript::Data::copy,args("other"),"Make this object a copy of ``other``\n"
510 "\n"
511 ":note: The two objects will act independently from now on. That is, changing ``other`` "
512 "after this call will not change this object and vice versa.")
513 .def("copy",&escript::Data::copySelf,":note: In the no argument form, a new object will be returned which is an independent copy of this object.")
514 .def("delay",&escript::Data::delay,"Convert this object into lazy representation")
515 .def("setValueOfDataPoint",&escript::Data::setValueOfDataPointToPyObject,args("dataPointNo","value"))
516 .def("setValueOfDataPoint",&escript::Data::setValueOfDataPointToArray)
517 .def("_setTupleForGlobalDataPoint", &escript::Data::setTupleForGlobalDataPoint)
518 .def("setValueOfDataPoint",&escript::Data::setValueOfDataPoint,"\n"
519 "Modify the value of a single datapoint.\n\n"
520 ":param dataPointNo:\n"
521 ":type dataPointNo: int\n"
522 ":param value: \n"
523 ":type value: ``float`` or an object which acts like an array, ``tuple`` or ``list``\n"
524 ":warning: Use of this operation is discouraged. It prevents some optimisations from operating.")
525 .def("getTupleForDataPoint",&escript::Data::getValueOfDataPointAsTuple,args("dataPointNo"),
526 ":return: Value of the specified datapoint\n"
527 ":rtype: ``tuple``\n"
528 ":param dataPointNo: datapoint to access\n"
529 ":type dataPointNo: ``int``")
530 .def("getTupleForGlobalDataPoint",&escript::Data::getValueOfGlobalDataPointAsTuple,args("procNo","dataPointNo"),"Get a specific datapoint from a specific process\n\n"
531 ":rtype: ``tuple``\n"
532 ":param procNo: MPI rank of the process\n"
533 ":type procNo: positive ``int``"
534 "\n"
535 ":param dataPointNo: datapoint to access\n"
536 ":type dataPointNo: int")
537 .def("setToZero",&escript::Data::setToZero,"After this call the object will store values of the same shape as before but all components will be zero.")
538 .def("interpolate",&escript::Data::interpolate,args("functionspace"),"Interpolate this object's values into a new functionspace.")
539 .def("_interpolateTable3d", &escript::Data::interpolateFromTable3DP,
540 (arg("table"),arg("Amin"),arg("Astep"), arg("B"), arg("Bmin"), arg("Bstep"), arg("C"), arg("Cmin"), arg("Cstep"), arg("undef")=1.e50, arg("check_boundaries")=false, "For internal use only. Please use the interpolateTable function.")
541 )
542
543 .def("interpolateTable", &escript::Data::interpolateFromTable2DP,
544 (arg("table"),arg("Amin"),arg("Astep"), arg("B"), arg("Bmin"), arg("Bstep"), arg("undef")=1.e50, arg("check_boundaries")=false),
545 "Creates a new Data object by interpolating using the source data (which are\n"
546 "looked up in ``table``)\n"
547 "``A`` must be the outer dimension on the table\n\n"
548 ":param table: two dimensional collection of values\n"
549 ":param Amin: The base of locations in table\n"
550 ":type Amin: float\n"
551 ":param Astep: size of gap between each item in the table\n"
552 ":type Astep: float\n"
553 ":param undef: upper bound on interpolated values\n"
554 ":type undef: float\n"
555 ":param B: Scalar representing the second coordinate to be mapped into the table\n"
556 ":type B: `Data`\n"
557 ":param Bmin: The base of locations in table for 2nd dimension\n"
558 ":type Bmin: float\n"
559 ":param Bstep: size of gap between each item in the table for 2nd dimension\n"
560 ":type Bstep: float\n"
561 ":param check_boundaries: if true, then values outside the boundaries will be rejected. If false, then boundary values will be used.\n"
562 ":raise RuntimeError(DataException): if the coordinates do not map into the table or if the interpolated value is above ``undef``"
563 "\n"
564 ":rtype: `Data`"
565 )
566 .def("interpolateTable", &escript::Data::interpolateFromTable1DP,
567 (arg("table"),arg("Amin"),arg("Astep"), arg("undef")=1.e50, arg("check_boundaries")=false)/*,
568 "Creates a new Data object by interpolating using the source data (which are\n"
569 "looked up in ``table``)\n\n"
570 ":param table: one dimensional collection of values\n"
571 ":param Amin: The base of locations in table\n"
572 ":type Amin: float\n"
573 ":param Astep: size of gap between each item in the table\n"
574 ":type Astep: float\n"
575 ":param undef: upper bound on interpolated values\n"
576 ":type undef: float\n"
577 ":param check_boundaries: if true, then values outside the boundaries will be rejected. If false, then boundary values will be used.\n"
578 ":raise RuntimeError(DataException): if the coordinates do not map into the table or if the interpolated value is above ``undef``"
579 "\n"
580 ":rtype: `Data`"
581 */
582 )
583 .def("nonuniformInterpolate", &escript::Data::nonuniforminterp, "1D interpolation with non equally spaced points",
584 (arg("in"), arg("out"), arg("check_boundaries")),
585 "Creates a Data object by linear interpolation of the function F(in)->out\n\n"
586 ":param in: input values of interpolation function\n"
587 ":param out: corresponding output values of interpolation function\n"
588 ":param check_boundaries: If True, an exception will the thrown if the data object contains values"
589 "outside the range given by ``in``.\n"
590 )
591 .def("nonuniformSlope", &escript::Data::nonuniformslope, "1D interpolation of slope with non equally spaced points",
592 (arg("in"), arg("out"), arg("check_boundaries")),
593 "Creates a Data object by computing the slope of the function F(in)->out\n\n"
594 ":param in: input values of interpolation function\n"
595 ":param out: corresponding output values of interpolation function\n"
596 ":param check_boundaries: If True, an exception will the thrown if the data object contains values"
597 "outside the range given by ``in``.\n"
598 )
599 .def("minGlobalDataPoint",&escript::Data::minGlobalDataPoint,"Please consider using getInfLocator() from pdetools instead.")
600 .def("maxGlobalDataPoint",&escript::Data::maxGlobalDataPoint, "Please consider using getSupLocator() from pdetools instead.")
601 .def("getTagNumber",&escript::Data::getTagNumber,args("dpno"),"Return tag number for the specified datapoint\n\n"
602 ":rtype: int\n"
603 ":param dpno: datapoint number\n"
604 ":type dpno: int")
605 // Unary functions for Data
606 .def("conjugate", &escript::Data::conjugate)
607 .def("real", &escript::Data::real)
608 .def("imag", &escript::Data::imag)
609 .def("promote", &escript::Data::complicate)
610 .def("_interpolate",&escript::Data::interpolate)
611 .def("_grad",&escript::Data::gradOn)
612 .def("_grad",&escript::Data::grad)
613 .def("_transpose",&escript::Data::transpose)
614 .def("_trace",&escript::Data::trace)
615 .def("_maxval",&escript::Data::maxval)
616 .def("_minval",&escript::Data::minval)
617 .def("_wherePositive",&escript::Data::wherePositive)
618 .def("_whereNegative",&escript::Data::whereNegative)
619 .def("_whereNonNegative",&escript::Data::whereNonNegative)
620 .def("_whereNonPositive",&escript::Data::whereNonPositive)
621 .def("_whereZero",&escript::Data::whereZero,(arg("tol")=0.0))
622 .def("_whereNonZero",&escript::Data::whereNonZero,(arg("tol")=0.0))
623 .def("_erf",&escript::Data::erf)
624 .def("_besselFirstKind",&escript::Data::besselFirstKind,arg("order"))
625 .def("_besselSecondKind",&escript::Data::besselSecondKind,arg("order"))
626 .def("_sin",&escript::Data::sin)
627 .def("_cos",&escript::Data::cos)
628 .def("_tan",&escript::Data::tan)
629 .def("_asin",&escript::Data::asin)
630 .def("_acos",&escript::Data::acos)
631 .def("_atan",&escript::Data::atan)
632 .def("_sinh",&escript::Data::sinh)
633 .def("_cosh",&escript::Data::cosh)
634 .def("_tanh",&escript::Data::tanh)
635 .def("_asinh",&escript::Data::asinh)
636 .def("_acosh",&escript::Data::acosh)
637 .def("_atanh",&escript::Data::atanh)
638 .def("_exp",&escript::Data::exp)
639 .def("_sqrt",&escript::Data::sqrt)
640 .def("_log10",&escript::Data::log10)
641 .def("_log",&escript::Data::log)
642 .def("_sign",&escript::Data::sign)
643 .def("_symmetric",&escript::Data::symmetric)
644 .def("_antisymmetric",&escript::Data::antisymmetric)
645 .def("_hermitian",&escript::Data::hermitian)
646 .def("_antihermitian",&escript::Data::antihermitian)
647 .def("_trace",&escript::Data::trace)
648 .def("_swap_axes",&escript::Data::swapaxes)
649 .def("_eigenvalues",&escript::Data::eigenvalues)
650 .def("_eigenvalues_and_eigenvectors",&escript::Data::eigenvalues_and_eigenvectors,(arg("tol")=1.e-13))
651 // functions returning a single real number:
652 .def("_Lsup",&escript::Data::Lsup,":return: the Lsup-norm of the object\n"
653 ":rtype: float\n"
654 ":note: If the ``Data`` contains no values, zero will be returned instead.")
655 .def("_sup",&escript::Data::sup,":return: the maximum value over all data points.\n"
656 ":rtype: float\n"
657 ":note: If the ``Data`` contains no values a large negative value will be returned instead.")
658 .def("_inf",&escript::Data::inf,":return: minimum value over all components and all data points\n"
659 ":rtype: float\n"
660 ":note: If the ``Data`` contains no values a large positive value will be returned instead.")
661 .def("_integrateToTuple",&escript::Data::integrateToTuple,":return: Calculate the integral over the function space domain as a python tuple\n"
662 ":rtype: tuple")
663 // following implements the python abs operator
664 .def("__abs__",&escript::Data::abs,":return: absolute value\n\n"
665 ":rtype: `Data`")
666 // following implements the python "-" negation operator
667 .def("__neg__",&escript::Data::neg, ":return: negation of the values in this object\n"
668 ":rtype: `Data`")
669 // following implements the python "+" identity operator
670 .def("__pos__",&escript::Data::pos, "\n"
671 "The unary + operator\n\n"
672 ":rtype: `Data`")
673 // following three functions implement the python [] operator
674 .def("__getitem__",&escript::Data::getItem,"Used by the python [] operator\n\n"
675 ":rtype: `Data`")
676 .def("__setitem__",&escript::Data::setItemO,"Used by the python [] operator")
677 .def("__setitem__",&escript::Data::setItemD,"Used by the python [] operator")
678 // following three functions implement the python ** operator
679 .def("__pow__",&escript::Data::powO,"Used by the python ** operator\n\n"
680 ":rtype: `Data`")
681 .def("__pow__",&escript::Data::powD)
682 .def("__rpow__",&escript::Data::rpowO,"\n"
683 "Used by the python ** operator\n\n"
684 ":rtype: `Data`")
685 // following two functions implement the newer python / operator
686 .def("__truediv__",&escript::Data::truedivO)
687 .def("__truediv__",&escript::Data::truedivD)
688 .def("__rtruediv__",&escript::Data::rtruedivO)
689 .def("__gt__",block_cmp_data)
690 .def("__lt__",block_cmp_data)
691 .def("__le__",block_cmp_data)
692 .def("__ge__",block_cmp_data)
693 // NOTE:: The order of these declarations is important. Anything
694 // declared before the generic declaration isn't found so the generic
695 // version will be called.
696 // .def(self + other<object>())
697 // .def(other<object>() + self)
698 // .def(self + self)
699 .def(self += other<object>())
700 .def(self += self)
701
702 // .def(self - other<object>())
703 // .def(other<object>() - self)
704 // .def(self - self)
705 .def(self -= other<object>())
706 .def(self -= self)
707
708 // .def(self * other<object>())
709 // .def(other<object>() * self)
710 // .def(self * self)
711 .def(self *= other<object>())
712 .def(self *= self)
713
714 // .def(self / other<object>())
715 // .def(other<object>() / self)
716 // .def(self / self)
717 .def(self /= other<object>())
718 .def(self /= self)
719 // Need scope resolution due to a bug either in the compiler or
720 // the boost code. This calls operator << for Data.
721 .def(self_ns::str(self))
722 .def("_inverse", &escript::Data::matrixInverse, ":return: inverse of square matrices\n"
723 "")
724 // .def("__add__", &escript::Data::addOperatorD)
725 .def("__add__", &escript::Data::__add__)
726 .def("__radd__", &escript::Data::__add__) // its the same coz + is commutative
727 .def("__sub__", &escript::Data::__sub__)
728 .def("__rsub__", &escript::Data::__rsub__)
729 .def("__mul__", &escript::Data::__mul__)
730 .def("__rmul__", &escript::Data::__mul__) // commutative
731 .def("__div__", &escript::Data::__div__)
732 .def("__rdiv__", &escript::Data::__rdiv__) // commutative
733 .def("__eq__", block_eq_data) // stop people from using ==
734 .def("__ne__", block_eq_data) // stop people from using !=
735 ;
736
737 //
738 // Factory methods for function space
739 //
740 def("ContinuousFunction",escript::continuousFunction,args("domain"),
741 ":return: a continuous FunctionSpace (overlapped node values)\n"
742 ":rtype: `FunctionSpace`");
743 def("ReducedContinuousFunction",escript::reducedContinuousFunction,args("domain"),
744 ":return: a continuous with reduced order FunctionSpace (overlapped node values on reduced element order)\n"
745 ":rtype: `FunctionSpace`");
746 def("Function",escript::function,args("domain"),":return: a function `FunctionSpace`\n"
747 ":rtype: `FunctionSpace`");
748 def("ReducedFunction",escript::reducedFunction, args("domain"),":return: a function FunctionSpace with reduced integration order\n"
749 ":rtype: `FunctionSpace`");
750 def("FunctionOnBoundary",escript::functionOnBoundary, args("domain"), ":return: a function on boundary FunctionSpace\n"
751 ":rtype: `FunctionSpace`");
752 def("ReducedFunctionOnBoundary",escript::reducedFunctionOnBoundary, args("domain"),
753 ":return: a function on boundary FunctionSpace with reduced integration order\n"
754 ":rtype: `FunctionSpace`");
755 def("FunctionOnContactZero",escript::functionOnContactZero, args("domain"), ":return: Return a FunctionSpace on left side of contact\n"
756 ":rtype: `FunctionSpace`");
757 def("ReducedFunctionOnContactZero",escript::reducedFunctionOnContactZero, args("domain"),
758 ":return: a FunctionSpace on left side of contact with reduced integration order\n"
759 ":rtype: `FunctionSpace`");
760 def("FunctionOnContactOne",escript::functionOnContactOne, args("domain"), ":return: Return a FunctionSpace on right side of contact\n"
761 ":rtype: `FunctionSpace`");
762 def("ReducedFunctionOnContactOne",escript::reducedFunctionOnContactOne, args("domain"),
763 ":return: Return a FunctionSpace on right side of contact with reduced integration order\n"
764 ":rtype: `FunctionSpace`");
765 def("Solution",escript::solution, args("domain"), ":rtype: `FunctionSpace`");
766 def("ReducedSolution",escript::reducedSolution, args("domain"), ":rtype: `FunctionSpace`");
767 def("DiracDeltaFunctions",escript::diracDeltaFunctions, args("domain"), ":rtype: `FunctionSpace`");
768
769
770
771
772
773 //
774 // Factory methods for Data
775 //
776 def("load",escript::load, args("fileName","domain"), "reads Data on domain from file in netCDF format\n\n"
777 ":param fileName:\n"
778 ":type fileName: ``string``\n"
779 ":param domain:\n"
780 ":type domain: `Domain`");
781 def("loadIsConfigured",escript::loadConfigured,":return: True if the load function is configured.");
782 def("Scalar",escript::Scalar,
783 (arg("value")=0.0,
784 arg("what")=escript::FunctionSpace(),
785 arg("expanded")=false),
786 "Construct a Data object containing scalar data-points.\n\n"
787 ":param value: scalar value for all points\n"
788 "\n"
789 ":rtype: `Data`\n"
790 ":type value: float\n"
791 ":param what: FunctionSpace for Data\n"
792 ":type what: `FunctionSpace`\n"
793 ":param expanded: If True, a value is stored for each point. If False, more efficient representations may be used\n"
794 ":type expanded: ``bool``");
795 def("Vector",escript::Vector,
796 (arg("value")=0.0,
797 arg("what")=escript::FunctionSpace(),
798 arg("expanded")=false),
799 "Construct a Data object containing rank1 data-points.\n\n"
800 ":param value: scalar value for all points\n"
801 "\n"
802 ":rtype: `Data`\n"
803 ":type value: float\n"
804 ":param what: FunctionSpace for Data\n"
805 ":type what: `FunctionSpace`\n"
806 ":param expanded: If True, a value is stored for each point. If False, more efficient representations may be used\n"
807 ":type expanded: ``bool``");
808 def("Vector", escript::VectorFromObj,
809 (arg("value"),
810 arg("what")=escript::FunctionSpace(),
811 arg("expanded")=false));
812 def("Tensor",escript::Tensor,
813 (arg("value")=0.0,
814 arg("what")=escript::FunctionSpace(),
815 arg("expanded")=false),
816 "Construct a Data object containing rank2 data-points.\n\n"
817 ":param value: scalar value for all points\n"
818 "\n"
819 ":rtype: `Data`\n"
820 ":type value: float\n"
821 ":param what: FunctionSpace for Data\n"
822 ":type what: `FunctionSpace`\n"
823 ":param expanded: If True, a value is stored for each point. If False, more efficient representations may be used\n"
824 ":type expanded: ``bool``");
825 def("Tensor", escript::TensorFromObj,
826 (arg("value"),
827 arg("what")=escript::FunctionSpace(),
828 arg("expanded")=false));
829 def("Tensor3",escript::Tensor3,
830 (arg("value")=0.0,
831 arg("what")=escript::FunctionSpace(),
832 arg("expanded")=false),
833 "Construct a Data object containing rank3 data-points.\n\n"
834 ":param value: scalar value for all points\n"
835 "\n"
836 ":rtype: `Data`\n"
837 ":type value: float\n"
838 ":param what: FunctionSpace for Data\n"
839 ":type what: `FunctionSpace`\n"
840 ":param expanded: If True, a value is stored for each point. If False, more efficient representations may be used\n"
841 ":type expanded: ``bool``"
842 );
843 def("Tensor3", escript::Tensor3FromObj,
844 (arg("value"),
845 arg("what")=escript::FunctionSpace(),
846 arg("expanded")=false));
847 def("Tensor4",escript::Tensor4,
848 (arg("value")=0.0,
849 arg("what")=escript::FunctionSpace(),
850 arg("expanded")=false),
851 "Construct a Data object containing rank4 data-points.\n\n"
852 ":param value: scalar value for all points\n"
853 "\n"
854 ":rtype: `Data`\n"
855 ":type value: float\n"
856 ":param what: FunctionSpace for Data\n"
857 ":type what: `FunctionSpace`\n"
858 ":param expanded: If True, a value is stored for each point. If False, more efficient representations may be used\n"
859 ":type expanded: ``bool``"
860 );
861 def("Tensor4", escript::Tensor4FromObj,
862 (arg("value"),
863 arg("what")=escript::FunctionSpace(),
864 arg("expanded")=false));
865
866
867 def("RandomData", escript::randomData, (arg("shape"), arg("fs"), arg("seed")=0, arg("filter")=boost::python::tuple()),
868 "Creates a new expanded Data object containing pseudo-random values. With no filter, values are drawn uniformly at random from [0,1].\n\n"
869 ":param shape: datapoint shape\n"
870 ":type shape: tuple\n"
871 ":param fs: function space for data object.\n"
872 ":type fs: `FunctionSpace`\n"
873 ":param seed: seed for random number generator.\n"
874 ":type seed: long\n"
875 "");
876
877 //
878 // Binary operators
879 //
880 def("C_GeneralTensorProduct",escript::C_GeneralTensorProduct,
881 (arg("arg0"),
882 arg("arg1"),
883 arg("axis_offset")=0,
884 arg("transpose")=0),
885 "Compute a tensor product of two Data objects.\n\n"
886 ":rtype: `Data`\n"
887 ":param arg0:\n"
888 ":param arg1:\n"
889 ":param axis_offset:\n"
890 ":type axis_offset: ``int``\n"
891 ":param transpose: 0: transpose neither, 1: transpose arg0, 2: transpose arg1\n"
892 ":type transpose: int");
893
894 //
895 // Interface for AbstractSystemMatrix
896 //
897 class_<escript::AbstractSystemMatrix,escript::ASM_ptr, boost::noncopyable>("Operator","",init<>()) // Doco goes in the empty string param
898 .def("isEmpty",&escript::AbstractSystemMatrix::isEmpty,":rtype: ``bool``\n"
899 ":return: True if matrix is empty")
900 .def("solve",&escript::AbstractSystemMatrix::solve, args("in","options"),
901 ":return: the solution *u* of the linear system *this*u=in*\n\n"
902 ":param in:\n"
903 ":type in: `Data`")
904 .def("of",&escript::AbstractSystemMatrix::vectorMultiply,args("right"),
905 "matrix*vector multiplication")
906 .def("nullifyRowsAndCols",&escript::AbstractSystemMatrix::nullifyRowsAndCols)
907 .def("saveMM",&escript::AbstractSystemMatrix::saveMM, args("fileName"),
908 "writes the matrix to a file using the Matrix Market file format")
909 .def("saveHB",&escript::AbstractSystemMatrix::saveHB, args("filename"),
910 "writes the matrix to a file using the Harwell-Boeing file format")
911 .def("resetValues",&escript::AbstractSystemMatrix::resetValues, "resets the matrix entries")
912 .def(self*other<escript::Data>());
913 //
914 // Interface for AbstractTransportProblem
915 //
916 class_<escript::AbstractTransportProblem, escript::ATP_ptr, boost::noncopyable >("TransportProblem","",init<>()) // Doco goes in the empty string param
917 .def("isEmpty",&escript::AbstractTransportProblem::isEmpty,":rtype: ``int``")
918 .def("solve",&escript::AbstractTransportProblem::solve, args("u0","source","dt", "options"),
919 "returns the solution *u* for a time step *dt>0* with initial value u0\n\n"
920 ":rtype: `Data`\n"
921 ":param source:\n"
922 ":type source: `Data`")
923 .def("insertConstraint",&escript::AbstractTransportProblem::insertConstraint,
924 args("source", "q", "r","factor"),
925 "inserts constraint *u_{,t}=r* where *q>0* into the problem using a weighting factor")
926 .def("reset",&escript::AbstractTransportProblem::resetTransport,
927 "resets the transport operator typically as they have been updated.")
928 .def("resetValues",&escript::AbstractTransportProblem::resetTransport)
929 .def("getSafeTimeStepSize",&escript::AbstractTransportProblem::getSafeTimeStepSize)
930 .def("getUnlimitedTimeStepSize",&escript::AbstractTransportProblem::getUnlimitedTimeStepSize);
931
932 enum_<escript::SolverOptions>("SolverOptions")
933 .value("DEFAULT", escript::SO_DEFAULT)
934
935 .value("TARGET_CPU", escript::SO_TARGET_CPU)
936 .value("TARGET_GPU", escript::SO_TARGET_GPU)
937
938 .value("CUSP", escript::SO_PACKAGE_CUSP)
939 .value("MKL", escript::SO_PACKAGE_MKL)
940 .value("PASO", escript::SO_PACKAGE_PASO)
941 .value("TRILINOS", escript::SO_PACKAGE_TRILINOS)
942 .value("UMFPACK", escript::SO_PACKAGE_UMFPACK)
943
944 .value("BICGSTAB", escript::SO_METHOD_BICGSTAB)
945 .value("CGLS", escript::SO_METHOD_CGLS)
946 .value("CGS", escript::SO_METHOD_CGS)
947 .value("CHOLEVSKY", escript::SO_METHOD_CHOLEVSKY)
948 .value("CR", escript::SO_METHOD_CR)
949 .value("DIRECT", escript::SO_METHOD_DIRECT)
950 .value("GMRES", escript::SO_METHOD_GMRES)
951 .value("HRZ_LUMPING", escript::SO_METHOD_HRZ_LUMPING)
952 .value("ITERATIVE", escript::SO_METHOD_ITERATIVE)
953 .value("LSQR", escript::SO_METHOD_LSQR)
954 .value("LUMPING", escript::SO_METHOD_ROWSUM_LUMPING)
955 .value("MINRES", escript::SO_METHOD_MINRES)
956 .value("NONLINEAR_GMRES", escript::SO_METHOD_NONLINEAR_GMRES)
957 .value("PCG", escript::SO_METHOD_PCG)
958 .value("PRES20", escript::SO_METHOD_PRES20)
959 .value("ROWSUM_LUMPING", escript::SO_METHOD_ROWSUM_LUMPING)
960 .value("TFQMR", escript::SO_METHOD_TFQMR)
961
962 .value("AMG", escript::SO_PRECONDITIONER_AMG)
963 .value("AMLI", escript::SO_PRECONDITIONER_AMLI)
964 .value("BOOMERAMG", escript::SO_PRECONDITIONER_BOOMERAMG)
965 .value("GAUSS_SEIDEL", escript::SO_PRECONDITIONER_GAUSS_SEIDEL)
966 .value("ILU0", escript::SO_PRECONDITIONER_ILU0)
967 .value("ILUT", escript::SO_PRECONDITIONER_ILUT)
968 .value("JACOBI", escript::SO_PRECONDITIONER_JACOBI)
969 .value("NO_PRECONDITIONER", escript::SO_PRECONDITIONER_NONE)
970 .value("REC_ILU", escript::SO_PRECONDITIONER_REC_ILU)
971 .value("RILU", escript::SO_PRECONDITIONER_RILU)
972
973 .value("BACKWARD_EULER", escript::SO_ODESOLVER_BACKWARD_EULER)
974 .value("CRANK_NICOLSON", escript::SO_ODESOLVER_CRANK_NICOLSON)
975 .value("LINEAR_CRANK_NICOLSON", escript::SO_ODESOLVER_LINEAR_CRANK_NICOLSON)
976
977 .value("CLASSIC_INTERPOLATION", escript::SO_INTERPOLATION_CLASSIC)
978 .value("CLASSIC_INTERPOLATION_WITH_FF_COUPLING", escript::SO_INTERPOLATION_CLASSIC_WITH_FF_COUPLING)
979 .value("DIRECT_INTERPOLATION", escript::SO_INTERPOLATION_DIRECT)
980
981 .value("AGGREGATION_COARSENING", escript::SO_COARSENING_AGGREGATION)
982 .value("CIJP_COARSENING", escript::SO_COARSENING_CIJP)
983 .value("CIJP_FIXED_RANDOM_COARSENING", escript::SO_COARSENING_CIJP_FIXED_RANDOM)
984 .value("FALGOUT_COARSENING", escript::SO_COARSENING_FALGOUT)
985 .value("HMIS_COARSENING", escript::SO_COARSENING_HMIS)
986 .value("PMIS_COARSENING", escript::SO_COARSENING_PMIS)
987 .value("RUGE_STUEBEN_COARSENING", escript::SO_COARSENING_RUGE_STUEBEN)
988 .value("STANDARD_COARSENING", escript::SO_COARSENING_STANDARD)
989 .value("YAIR_SHAPIRA_COARSENING", escript::SO_COARSENING_YAIR_SHAPIRA)
990
991 .value("DEFAULT_REORDERING", escript::SO_REORDERING_DEFAULT)
992 .value("MINIMUM_FILL_IN", escript::SO_REORDERING_MINIMUM_FILL_IN)
993 .value("NESTED_DISSECTION", escript::SO_REORDERING_NESTED_DISSECTION)
994 .value("NO_REORDERING", escript::SO_REORDERING_NONE);
995
996
997 class_<escript::SolverBuddy, escript::SB_ptr >("SolverBuddy","",init<>())
998 .def("getSummary", &escript::SolverBuddy::getSummary,"Returns a string reporting the current settings")
999 .def("__str__", &escript::SolverBuddy::getSummary)
1000 .def("getName", &escript::SolverBuddy::getName, args("key"),"Returns the name of a given key\n\n"
1001 ":param key: a valid key")
1002 .def("resetDiagnostics", &escript::SolverBuddy::resetDiagnostics, args("all")=false,"Resets the diagnostics\n\n"
1003 ":param all: if ``all`` is ``True`` all diagnostics including accumulative counters are reset.\n"
1004 ":type all: ``bool``")
1005 .def("_updateDiagnostics", &escript::SolverBuddy::updateDiagnostics, args("key", "value"),"Updates diagnostic information\n\n"
1006 ":param name: name of diagnostic information\n"
1007 ":type name: ``str`` in the list 'num_iter', 'num_level',\n"
1008 "'num_inner_iter', 'time', 'set_up_time', 'net_time',\n"
1009 "'residual_norm', 'converged'.\n"
1010 ":param value: new value of the diagnostic information\n"
1011 ":note: this function is used by a solver to report diagnostics\n"
1012 "information.")
1013 .def("getDiagnostics", &escript::SolverBuddy::getDiagnostics, args("name"),"Returns the diagnostic information ``name``. Possible values are:\n\n"
1014 "- 'num_iter': the number of iteration steps\n"
1015 "- 'cum_num_iter': the cumulative number of iteration steps\n"
1016 "- 'num_level': the number of level in multi level solver\n"
1017 "- 'num_inner_iter': the number of inner iteration steps\n"
1018 "- 'cum_num_inner_iter': the cumulative number of inner iteration steps\n"
1019 "- 'time': execution time\n"
1020 "- 'cum_time': cumulative execution time\n"
1021 "- 'set_up_time': time to set up of the solver, typically this includes factorization and reordering\n"
1022 "- 'cum_set_up_time': cumulative time to set up of the solver\n"
1023 "- 'net_time': net execution time, excluding setup time for the solver and execution time for preconditioner\n"
1024 "- 'cum_net_time': cumulative net execution time\n"
1025 "- 'preconditioner_size': size of preconditioner [Bytes]\n"
1026 "- 'converged': return True if solution has converged.\n"
1027 "- 'time_step_backtracking_used': returns True if time step back tracking has been used.\n"
1028 "- 'coarse_level_sparsity': returns the sparsity of the matrix on the coarsest level\n"
1029 "- 'num_coarse_unknowns': returns the number of unknowns on the coarsest level\n\n\n"
1030 ":param name: name of diagnostic information to return\n"
1031 ":type name: ``str`` in the list above.\n"
1032 ":return: requested value. 0 is returned if the value is yet to be defined.\n"
1033 ":note: If the solver has thrown an exception diagnostic values have an undefined status.")
1034 .def("hasConverged", &escript::SolverBuddy::hasConverged,"Returns ``True`` if the last solver call has been finalized successfully.\n\n"
1035 ":note: if an exception has been thrown by the solver the status of this"
1036 "flag is undefined.\n")
1037 .def("setCoarsening", &escript::SolverBuddy::setCoarsening, args("coarsening"),"Sets the key of the coarsening method to be applied in AMG or AMLI or BoomerAMG\n\n"
1038 ":param method: selects the coarsening method .\n"
1039 ":type method: in `DEFAULT`, `YAIR_SHAPIRA_COARSENING`, `RUGE_STUEBEN_COARSENING`, `AGGREGATION_COARSENING`, `CIJP_FIXED_RANDOM_COARSENING`, `CIJP_COARSENING`, `FALGOUT_COARSENING`, `PMIS_COARSENING`, `HMIS_COARSENING`")
1040 .def("getCoarsening", &escript::SolverBuddy::getCoarsening,"Returns the key of the coarsening algorithm to be applied AMG, AMLI or BoomerAMG\n\n"
1041 ":rtype: in the list `DEFAULT`, `YAIR_SHAPIRA_COARSENING`, `RUGE_STUEBEN_COARSENING`, `AGGREGATION_COARSENING`, `CIJP_FIXED_RANDOM_COARSENING`, `CIJP_COARSENING`, `FALGOUT_COARSENING`, `PMIS_COARSENING`, `HMIS_COARSENING`")
1042 .def("setMinCoarseMatrixSize", &escript::SolverBuddy::setMinCoarseMatrixSize, args("size"),"Sets the minimum size of the coarsest level matrix in AMG or AMLI\n\n"
1043 ":param size: minimum size of the coarsest level matrix .\n"
1044 ":type size: positive ``int``")
1045 .def("getMinCoarseMatrixSize", &escript::SolverBuddy::getMinCoarseMatrixSize,"Returns the minimum size of the coarsest level matrix in AMG or AMLI")
1046 .def("setPreconditioner", &escript::SolverBuddy::setPreconditioner, args("preconditioner"),"Sets the preconditioner to be used.\n\n"
1047 ":param preconditioner: key of the preconditioner to be used.\n"
1048 ":type preconditioner: in `ILU0`, `ILUT`, `JACOBI`, `AMG`, `AMLI`, `REC_ILU`, `GAUSS_SEIDEL`, `RILU`, `BOOMERAMG`, `NO_PRECONDITIONER`\n"
1049 ":note: Not all packages support all preconditioner. It can be assumed that a package makes a reasonable choice if it encounters an unknown"
1050 "preconditioner.\n")
1051 .def("getPreconditioner", &escript::SolverBuddy::getPreconditioner,"Returns the key of the preconditioner to be used.\n\n"
1052 ":rtype: in the list `ILU0`, `ILUT`, `JACOBI`, `AMLI`, `AMG`, `REC_ILU`, `GAUSS_SEIDEL`, `RILU`, `BOOMERAMG`, `NO_PRECONDITIONER`")
1053 .def("setSmoother", &escript::SolverBuddy::setSmoother, args("smoother"),"Sets the smoother to be used.\n\n"
1054 ":param smoother: key of the smoother to be used.\n"
1055 ":type smoother: in `JACOBI`, `GAUSS_SEIDEL`\n"
1056 ":note: Not all packages support all smoothers. It can be assumed that a package makes a reasonable choice if it encounters an unknown smoother.")
1057 .def("getSmoother", &escript::SolverBuddy::getSmoother,"Returns key of the smoother to be used.\n\n"
1058 ":rtype: in the list `JACOBI`, `GAUSS_SEIDEL`")
1059 .def("setSolverMethod", &escript::SolverBuddy::setSolverMethod, args("method"),"Sets the solver method to be used. Use ``method``=``DIRECT`` to indicate that a direct rather than an iterative solver should be used and use ``method``=``ITERATIVE`` to indicate that an iterative rather than a direct solver should be used.\n\n"
1060 ":param method: key of the solver method to be used.\n"
1061 ":type method: in `DEFAULT`, `DIRECT`, `CHOLEVSKY`, `PCG`, `CR`, `CGS`, `BICGSTAB`, `GMRES`, `PRES20`, `ROWSUM_LUMPING`, `HRZ_LUMPING`, `ITERATIVE`, `NONLINEAR_GMRES`, `TFQMR`, `MINRES`\n"
1062 ":note: Not all packages support all solvers. It can be assumed that a package makes a reasonable choice if it encounters an unknown solver method.")
1063 .def("getSolverMethod", &escript::SolverBuddy::getSolverMethod,"Returns key of the solver method to be used.\n\n"
1064 ":rtype: in the list `DEFAULT`, `DIRECT`, `CHOLEVSKY`, `PCG`, `CR`, `CGS`, `BICGSTAB`, `GMRES`, `PRES20`, `ROWSUM_LUMPING`, `HRZ_LUMPING`, `MINRES`, `ITERATIVE`, `NONLINEAR_GMRES`, `TFQMR`")
1065 .def("setPackage", &escript::SolverBuddy::setPackage, args("package"),"Sets the solver package to be used as a solver.\n\n"
1066 ":param package: key of the solver package to be used.\n"
1067 ":type package: in `DEFAULT`, `PASO`, `CUSP`, `MKL`, `UMFPACK`, `TRILINOS`\n"
1068 ":note: Not all packages are support on all implementation. An exception may be thrown on some platforms if a particular package is requested.")
1069 .def("getPackage", &escript::SolverBuddy::getPackage,"Returns the solver package key\n\n"
1070 ":rtype: in the list `DEFAULT`, `PASO`, `CUSP`, `MKL`, `UMFPACK`, `TRILINOS`")
1071 .def("setSolverTarget", &escript::SolverBuddy::setSolverTarget, args("target"),"Sets the solver target to be used.\n\n"
1072 ":param target: key of the solver target to be used.\n"
1073 ":type target: in `TARGET_CPU`, `TARGET_GPU`\n")
1074 .def("getSolverTarget", &escript::SolverBuddy::getSolverTarget, "Returns the solver target key\n\n"
1075 ":rtype: in the list `TARGET_CPU`, `TARGET_GPU`")
1076 .def("setReordering", &escript::SolverBuddy::setReordering, args("ordering"),"Sets the key of the reordering method to be applied if supported by the solver. Some direct solvers support reordering to optimize compute time and storage use during elimination.\n\n"
1077 ":param ordering: selects the reordering strategy.\n"
1078 ":type ordering: in 'NO_REORDERING', 'MINIMUM_FILL_IN', 'NESTED_DISSECTION', 'DEFAULT_REORDERING'")
1079 .def("getReordering", &escript::SolverBuddy::getReordering,"Returns the key of the reordering method to be applied if supported by the solver.\n\n"
1080 ":rtype: in `NO_REORDERING`, `MINIMUM_FILL_IN`, `NESTED_DISSECTION`, `DEFAULT_REORDERING`")
1081 .def("setRestart", &escript::SolverBuddy::setRestart, args("restart"),"Sets the number of iterations steps after which GMRES performs a restart.\n\n"
1082 ":param restart: number of iteration steps after which to perform a restart. If 0 no restart is performed.\n"
1083 ":type restart: ``int``")
1084 .def("getRestart", &escript::SolverBuddy::getRestart,"Returns the number of iterations steps after which GMRES performs a restart. If 0 is returned no restart is performed.\n\n"
1085 ":rtype: ``int``")
1086 .def("setDiagonalDominanceThreshold", &escript::SolverBuddy::setDiagonalDominanceThreshold, args("threshold"),"Sets the threshold for diagonal dominant rows which are eliminated during AMG coarsening.\n\n"
1087 ":param value: threshold\n"
1088 ":type value: ``float``")
1089 .def("getDiagonalDominanceThreshold", &escript::SolverBuddy::getDiagonalDominanceThreshold,"Returns the threshold for diagonal dominant rows which are eliminated during AMG coarsening.\n\n"
1090 ":rtype: ``float``")
1091 .def("setTruncation", &escript::SolverBuddy::setTruncation, args("truncation"),"Sets the number of residuals in GMRES to be stored for orthogonalization. The more residuals are stored the faster GMRES converged\n\n"
1092 ":param truncation: truncation\n"
1093 ":type truncation: ``int``")
1094 .def("getTruncation", &escript::SolverBuddy::getTruncation,"Returns the number of residuals in GMRES to be stored for orthogonalization\n\n"
1095 ":rtype: ``int``")
1096 .def("setInnerIterMax", &escript::SolverBuddy::setInnerIterMax, args("iter_max"),"Sets the maximum number of iteration steps for the inner iteration.\n\n"
1097 ":param iter_max: maximum number of inner iterations\n"
1098 ":type iter_max: ``int``")
1099 .def("getInnerIterMax", &escript::SolverBuddy::getInnerIterMax,"Returns maximum number of inner iteration steps\n\n"
1100 ":rtype: ``int``")
1101 .def("setIterMax", &escript::SolverBuddy::setIterMax, args("iter_max"),"Sets the maximum number of iteration steps\n\n"
1102 ":param iter_max: maximum number of iteration steps\n"
1103 ":type iter_max: ``int``")
1104 .def("getIterMax", &escript::SolverBuddy::getIterMax,"Returns maximum number of iteration steps\n\n"
1105 ":rtype: ``int``")
1106 .def("setLevelMax", &escript::SolverBuddy::setLevelMax, args("level_max"),"Sets the maximum number of coarsening levels to be used in an algebraic multi-level solver or preconditioner\n\n"
1107 ":param level_max: maximum number of levels\n"
1108 ":type level_max: ``int``")
1109 .def("getLevelMax", &escript::SolverBuddy::getLevelMax,"Returns the maximum number of coarsening levels to be used in an algebraic multi level solver or preconditioner\n\n"
1110 ":rtype: ``int``")
1111 .def("setCycleType", &escript::SolverBuddy::setCycleType, args("cycle_type"),"Sets the cycle type (V-cycle or W-cycle) to be used in an algebraic multi-level solver or preconditioner\n\n"
1112 ":param cycle_type: the type of cycle\n"
1113 ":type cycle_type: ``int``")
1114 .def("getCycleType", &escript::SolverBuddy::getCycleType,"Returns the cyle type (V- or W-cycle) to be used in an algebraic multi level solver or preconditioner\n\n"
1115 ":rtype: ``int``")
1116 .def("setCoarseningThreshold", &escript::SolverBuddy::setCoarseningThreshold, args("theta"),"Sets the threshold for coarsening in the algebraic multi level solver or\n"
1117 "preconditioner\n\n"
1118 ":param theta: threshold for coarsening\n"
1119 ":type theta: positive ``float``")
1120 .def("getCoarseningThreshold", &escript::SolverBuddy::getCoarseningThreshold,"Returns the threshold for coarsening in the algebraic multi level solver\n"
1121 "or preconditioner\n\n"
1122 ":rtype: ``float``")
1123 .def("setNumSweeps", &escript::SolverBuddy::setNumSweeps, args("sweeps"),"Sets the number of sweeps in a Jacobi or Gauss-Seidel/SOR preconditioner.\n\n"
1124 ":param sweeps: number of sweeps\n"
1125 ":type sweeps: positive ``int``")
1126 .def("getNumSweeps", &escript::SolverBuddy::getNumSweeps,"Returns the number of sweeps in a Jacobi or Gauss-Seidel/SOR preconditioner.\n\n"
1127 ":rtype: ``int``")
1128 .def("setNumPreSweeps", &escript::SolverBuddy::setNumPreSweeps, args("sweeps"),"Sets the number of sweeps in the pre-smoothing step of a multi level\n"
1129 "solver or preconditioner\n\n"
1130 ":param sweeps: number of sweeps\n"
1131 ":type sweeps: positive ``int``")
1132 .def("getNumPreSweeps", &escript::SolverBuddy::getNumPreSweeps,"Returns he number of sweeps in the pre-smoothing step of a multi level solver or preconditioner\n\n"
1133 ":rtype: ``int``")
1134 .def("setNumPostSweeps", &escript::SolverBuddy::setNumPostSweeps, args("sweeps"),"Sets the number of sweeps in the post-smoothing step of a multi level\n"
1135 "solver or preconditioner\n\n"
1136 ":param sweeps: number of sweeps\n"
1137 ":type sweeps: positive ``int``")
1138 .def("getNumPostSweeps", &escript::SolverBuddy::getNumPostSweeps,"Returns he number of sweeps in the post-smoothing step of a multi level solver or preconditioner\n\n"
1139 ":rtype: ``int``")
1140 .def("setTolerance", &escript::SolverBuddy::setTolerance, args("rtol"),"Sets the relative tolerance for the solver\n\n"
1141 ":param rtol: relative tolerance\n"
1142 ":type rtol: non-negative ``float``")
1143 .def("getTolerance", &escript::SolverBuddy::getTolerance,"Returns the relative tolerance for the solver\n\n"
1144 ":rtype: ``float``")
1145 .def("setAbsoluteTolerance", &escript::SolverBuddy::setAbsoluteTolerance, args("atol"),"Sets the absolute tolerance for the solver\n\n"
1146 ":param atol: absolute tolerance\n"
1147 ":type atol: non-negative ``float``")
1148 .def("getAbsoluteTolerance", &escript::SolverBuddy::getAbsoluteTolerance,"Returns the absolute tolerance for the solver\n\n"
1149 ":rtype: ``float``")
1150 .def("setInnerTolerance", &escript::SolverBuddy::setInnerTolerance, args("rtol"),"Sets the relative tolerance for an inner iteration scheme, for instance on the coarsest level in a multi-level scheme.\n\n"
1151 ":param rtol: inner relative tolerance\n"
1152 ":type rtol: positive ``float``")
1153 .def("getInnerTolerance", &escript::SolverBuddy::getInnerTolerance,"Returns the relative tolerance for an inner iteration scheme\n\n"
1154 ":rtype: ``float``")
1155 .def("setDropTolerance", &escript::SolverBuddy::setDropTolerance, args("drop_tol"),"Sets the relative drop tolerance in ILUT\n\n"
1156 ":param drop_tol: drop tolerance\n"
1157 ":type drop_tol: positive ``float``")
1158 .def("getDropTolerance", &escript::SolverBuddy::getDropTolerance,"Returns the relative drop tolerance in ILUT\n\n"
1159 ":rtype: ``float``")
1160 .def("setDropStorage", &escript::SolverBuddy::setDropStorage, args("drop"),"Sets the maximum allowed increase in storage for ILUT. ``storage`` =2 would mean that a doubling of the storage needed for the coefficient matrix is\n"
1161 "allowed in the ILUT factorization.\n\n"
1162 ":param storage: allowed storage increase\n"
1163 ":type storage: ``float``")
1164 .def("getDropStorage", &escript::SolverBuddy::getDropStorage,"Returns the maximum allowed increase in storage for ILUT\n\n"
1165 ":rtype: ``float``")
1166 .def("setRelaxationFactor", &escript::SolverBuddy::setRelaxationFactor, args("relaxation"),"Sets the relaxation factor used to add dropped elements in RILU to the main diagonal.\n\n"
1167 ":param factor: relaxation factor\n"
1168 ":type factor: ``float``\n"
1169 ":note: RILU with a relaxation factor 0 is identical to ILU0")
1170 .def("getRelaxationFactor", &escript::SolverBuddy::getRelaxationFactor,"Returns the relaxation factor used to add dropped elements in RILU to the main diagonal.\n\n"
1171 ":rtype: ``float``")
1172 .def("isComplex", &escript::SolverBuddy::isComplex,"Checks if the coefficient matrix is set to be complex-valued.\n\n"
1173 ":return: True if a complex-valued PDE is indicated, False otherwise\n"
1174 ":rtype: ``bool``")
1175 .def("setComplex", &escript::SolverBuddy::setComplex, args("complex"),"Sets the complex flag for the coefficient matrix to ``flag``.\n\n"
1176 ":param flag: If True, the complex flag is set otherwise reset.\n"
1177 ":type flag: ``bool``")
1178 .def("isSymmetric", &escript::SolverBuddy::isSymmetric,"Checks if symmetry of the coefficient matrix is indicated.\n\n"
1179 ":return: True if a symmetric PDE is indicated, False otherwise\n"
1180 ":rtype: ``bool``")
1181 .def("setSymmetryOn", &escript::SolverBuddy::setSymmetryOn,"Sets the symmetry flag to indicate that the coefficient matrix is symmetric.")
1182 .def("setSymmetryOff", &escript::SolverBuddy::setSymmetryOff,"Clears the symmetry flag for the coefficient matrix.")
1183 .def("setSymmetry", &escript::SolverBuddy::setSymmetry, args("symmetry"),"Sets the symmetry flag for the coefficient matrix to ``flag``.\n\n"
1184 ":param flag: If True, the symmetry flag is set otherwise reset.\n"
1185 ":type flag: ``bool``")
1186 .def("isVerbose", &escript::SolverBuddy::isVerbose,"Returns ``True`` if the solver is expected to be verbose.\n\n"
1187 ":return: True if verbosity of switched on.\n"
1188 ":rtype: ``bool``")
1189 .def("setVerbosityOn", &escript::SolverBuddy::setVerbosityOn,"Switches the verbosity of the solver on.")
1190 .def("setVerbosityOff", &escript::SolverBuddy::setVerbosityOff,"Switches the verbosity of the solver off.")
1191 .def("setVerbosity", &escript::SolverBuddy::setVerbosity, args("verbosity"),"Sets the verbosity flag for the solver to ``flag``.\n\n"
1192 ":param verbose: If ``True``, the verbosity of the solver is switched on.\n"
1193 ":type verbose: ``bool``")
1194 .def("adaptInnerTolerance", &escript::SolverBuddy::adaptInnerTolerance,"Returns ``True`` if the tolerance of the inner solver is selected automatically. Otherwise the inner tolerance set by `setInnerTolerance` is used.\n\n"
1195 ":return: ``True`` if inner tolerance adaption is chosen.\n"
1196 ":rtype: ``bool``")
1197 .def("setInnerToleranceAdaptionOn", &escript::SolverBuddy::setInnerToleranceAdaptionOn,"Switches the automatic selection of inner tolerance on")
1198 .def("setInnerToleranceAdaptionOff", &escript::SolverBuddy::setInnerToleranceAdaptionOff,"Switches the automatic selection of inner tolerance off.")
1199 .def("setInnerToleranceAdaption", &escript::SolverBuddy::setInnerToleranceAdaption, args("adapt"),"Sets the flag to indicate automatic selection of the inner tolerance.\n\n"
1200 ":param adapt: If ``True``, the inner tolerance is selected automatically.\n"
1201 ":type adapt: ``bool``")
1202 .def("acceptConvergenceFailure", &escript::SolverBuddy::acceptConvergenceFailure,"Returns ``True`` if a failure to meet the stopping criteria within the given number of iteration steps is not raising in exception. This is useful\n"
1203 "if a solver is used in a non-linear context where the non-linear solver can continue even if the returned the solution does not necessarily meet the stopping criteria. One can use the `hasConverged` method to check if the\n"
1204 "last call to the solver was successful.\n\n"
1205 ":return: ``True`` if a failure to achieve convergence is accepted.\n"
1206 ":rtype: ``bool``")
1207 .def("setAcceptanceConvergenceFailureOn", &escript::SolverBuddy::setAcceptanceConvergenceFailureOn,"Switches the acceptance of a failure of convergence on")
1208 .def("setAcceptanceConvergenceFailureOff", &escript::SolverBuddy::setAcceptanceConvergenceFailureOff,"Switches the acceptance of a failure of convergence off.")
1209 .def("setAcceptanceConvergenceFailure", &escript::SolverBuddy::setAcceptanceConvergenceFailure, args("accept"),"Sets the flag to indicate the acceptance of a failure of convergence.\n\n"
1210 ":param accept: If ``True``, any failure to achieve convergence is accepted.\n"
1211 ":type accept: ``bool``")
1212 .def("useLocalPreconditioner", &escript::SolverBuddy::useLocalPreconditioner,"Returns ``True`` if the preconditoner is applied locally on each MPI. This reduces communication costs and speeds up the application of the preconditioner but at the costs of more iteration steps. This can be an advantage on clusters with slower interconnects.\n\n"
1213 ":return: ``True`` if local preconditioning is applied\n"
1214 ":rtype: ``bool``")
1215 .def("setLocalPreconditionerOn", &escript::SolverBuddy::setLocalPreconditionerOn,"Sets the flag to use local preconditioning to on")
1216 .def("setLocalPreconditionerOff", &escript::SolverBuddy::setLocalPreconditionerOff,"Sets the flag to use local preconditioning to off")
1217 .def("setLocalPreconditioner", &escript::SolverBuddy::setLocalPreconditioner, args("local"),"Sets the flag to use local preconditioning\n\n"
1218 ":param use: If ``True``, local preconditioning on each MPI rank is applied\n"
1219 ":type use: ``bool``")
1220 .def("setMinCoarseMatrixSparsity", &escript::SolverBuddy::setMinCoarseMatrixSparsity, args("sparsity"),"Sets the minimum sparsity on the coarsest level. Typically a direct solver is used when the sparsity becomes bigger than the set limit.\n\n"
1221 ":param sparsity: minimal sparsity\n"
1222 ":type sparsity: ``float``")
1223 .def("getMinCoarseMatrixSparsity", &escript::SolverBuddy::getMinCoarseMatrixSparsity,"Returns the minimum sparsity on the coarsest level. Typically a direct solver is used when the sparsity becomes bigger than the set limit.\n\n"
1224 ":return: minimal sparsity\n"
1225 ":rtype: ``float``")
1226 .def("setNumRefinements", &escript::SolverBuddy::setNumRefinements, args("refinements"),"Sets the number of refinement steps to refine the solution when a direct solver is applied.\n\n"
1227 ":param refinements: number of refinements\n"
1228 ":type refinements: non-negative ``int``")
1229 .def("getNumRefinements", &escript::SolverBuddy::getNumRefinements,"Returns the number of refinement steps to refine the solution when a direct solver is applied.\n\n"
1230 ":rtype: non-negative ``int``")
1231 .def("setNumCoarseMatrixRefinements", &escript::SolverBuddy::setNumCoarseMatrixRefinements, args("refinements"),"Sets the number of refinement steps to refine the solution on the coarsest level when a direct solver is applied.\n\n"
1232 ":param refinements: number of refinements\n"
1233 ":type refinements: non-negative ``int``")
1234 .def("getNumCoarseMatrixRefinements", &escript::SolverBuddy::getNumCoarseMatrixRefinements,"Returns the number of refinement steps to refine the solution on the coarsest level when a direct solver is applied.\n\n"
1235 ":rtype: non-negative ``int``")
1236 .def("usePanel", &escript::SolverBuddy::usePanel,"Returns ``True`` if a panel is used to search for unknown in the AMG coarsening, The panel approach is normally faster but can lead to larger coarse level systems.\n\n"
1237 ":return: ``True`` if a panel is used to find unknowns in AMG coarsening\n"
1238 ":rtype: ``bool``")
1239 .def("setUsePanelOn", &escript::SolverBuddy::setUsePanelOn,"Sets the flag to use a panel to find unknowns in AMG coarsening")
1240 .def("setUsePanelOff", &escript::SolverBuddy::setUsePanelOff,"Sets the flag to use a panel to find unknowns in AMG coarsening to off")
1241 .def("setUsePanel", &escript::SolverBuddy::setUsePanel, args("use"),"Sets the flag to use a panel to find unknowns in AMG coarsening\n\n"
1242 ":param use: If ``True``,a panel is used to find unknowns in AMG coarsening\n"
1243 ":type use: ``bool``")
1244 .def("setAMGInterpolation", &escript::SolverBuddy::setAMGInterpolation, args("interpolation"),"Set the interpolation method for the AMG preconditioner.\n\n"
1245 ":param method: key of the interpolation method to be used.\n"
1246 ":type method: in `CLASSIC_INTERPOLATION_WITH_FF_COUPLING`, `CLASSIC_INTERPOLATION`, `DIRECT_INTERPOLATION`")
1247 .def("getAMGInterpolation", &escript::SolverBuddy::getAMGInterpolation,"Returns key of the interpolation method for the SAMG preconditioner\n\n"
1248 ":rtype: in the list `CLASSIC_INTERPOLATION_WITH_FF_COUPLING`, `CLASSIC_INTERPOLATION`, `DIRECT_INTERPOLATION`")
1249 .def("setODESolver", &escript::SolverBuddy::setODESolver, args("solver"),"Set the solver method for ODEs.\n\n"
1250 ":param method: key of the ODE solver method to be used.\n"
1251 ":type method: in `CRANK_NICOLSON`, `BACKWARD_EULER`, `LINEAR_CRANK_NICOLSON`")
1252 .def("getODESolver", &escript::SolverBuddy::getODESolver,"Returns key of the solver method for ODEs.\n\n"
1253 ":param method: key of the ODE solver method to be used.\n"
1254 ":type method: in `CRANK_NICOLSON`, `BACKWARD_EULER`, `LINEAR_CRANK_NICOLSON`");
1255
1256
1257 // Functions to get/modify global parameters/features
1258 def("setEscriptParamInt", escript::setEscriptParamInt,
1259 (arg("name"), arg("value")=0), "Modify the value of an escript tuning parameter\n\n"
1260 ":param name:\n"
1261 ":type name: ``string``\n"
1262 ":param value:\n"
1263 ":type value: ``int``");
1264
1265 def("getEscriptParamInt", escript::getEscriptParamInt,
1266 (arg("name"),arg("sentinel")=0), "Read the value of an escript tuning parameter\n\n"
1267 ":param name: parameter to lookup\n"
1268 ":type name: ``string``\n"
1269 ":param sentinel: Value to be returned if ``name`` is not a known parameter\n"
1270 ":type sentinel: ``int``");
1271
1272 def("listEscriptParams", escript::listEscriptParams,
1273 ":return: A list of tuples (p,v,d) where p is the name of a parameter "
1274 "for escript, v is its current value, and d is a description.");
1275
1276 def("hasFeature", escript::hasFeature,
1277 (arg("name")), "Check if escript was compiled with a certain feature\n\n"
1278 ":param name: feature to lookup\n"
1279 ":type name: ``string``");
1280 def("listFeatures", escript::listFeatures,
1281 ":return: A list of strings representing the features escript supports.");
1282
1283 def("resolveGroup", escript::resolveGroup);
1284
1285 #ifdef IKNOWWHATIMDOING
1286 def("applyBinaryCFunction", escript::applyBinaryCFunction,
1287 (arg("function"), arg("outshape"), arg("in1"), arg("in2"))
1288 );
1289 #endif
1290
1291 def("_condEval", escript::condEval, (arg("mask"), arg("trueval"), arg("falseval")));
1292 }
1293

Properties

Name Value
svn:eol-style native
svn:keywords Author Date Id Revision

  ViewVC Help
Powered by ViewVC 1.1.26