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

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

Parent Directory Parent Directory | Revision Log Revision Log


Revision 6799 - (hide annotations)
Mon Mar 25 05:53:58 2019 UTC (8 weeks, 1 day ago) by aellery
File size: 71446 byte(s)
I have rewritten the solverbuddy. Briefly:

1. The remaining AMG code has been removed from PASO.
2. If Trilinos is available, escript will now use it by default.
3. eScript will use a direct solver by default, (if one is available,) when solving 2 dimensional problems and an iterative solver, by default, when solving 3 dimensional problems. This can be changed by a user by manually specifying which solver to use.
4. There is a new option available, setHermitian(), that allows a user to specify when a coefficient matrix is Hermitian.
5. Symmetry information is always passed onto the Trilinos solver when this information is relevant.
6. All tests have been updated, when relevant, to reflect these changes.
7. I fixed a couple of undocumented bugs.


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

Properties

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

  ViewVC Help
Powered by ViewVC 1.1.26