1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
|
# Python Interface
The Python interface uses `c_types` and links to the C interface of Tasmanian
as well as several additional C-style functions, e.g., when dealing with Addon templates.
The C++ classes are converted to `void*` pointers and then wrapped inside Python
classes with near identical interface.
The C++ vectors are replaced by 1D and 2D `numpy.ndarray` structures,
the enumerated types are replaced by strings,
and the C++ `std::function` and `lambda` expressions by Python callable objects and lambdas.
See the Fortran 2003 comments about the row major matrix format.
### Requirements
Python 3 is the only version currently tested and Tasmanian uses the following modules:
* **required** `sys`
* **required** `c_types`
* **required** `numpy`
* **optional** `matplotlib.pyplot`
Tasmanian is also available through PIP: [https://pypi.org/project/Tasmanian/](https://pypi.org/project/Tasmanian/);
however, the PIP installation comes with additional requirements for facilitating the CMake build process.
See the PIP section on the installation instructions page.
### Module
Starting with Tasmanian 7.0 all Python capabilities are included in a single module:
```
import Tasmanian
```
Note that the Tasmanian install path must be included in the Python search path:
```
<install-prefix>/lib/pythonX.Y/site-packages/ # following the Python convention
<install-prefix>/share/Tasmanian/python/ # Tasmanian version independent path
```
Either path is sufficient if it is added to the environment variable `PYTHONPATH`
(e.g., via the `TasmanianENVsetup.sh` script) or with the `sys.path.append()` command.
Example for creating an instance of a sparse grid:
```
import Tasmanian
grid = Tasmanian.SparseGrid()
grid.makeGlobalGrid(...)
```
Example for using DREAM sampling:
```
import Tasmanian
state = Tasmanian.DREAM.State(...)
state.setState(Tasmanian.DREAM.genUniformSamples(...))
Tasmanian.DREAM.Sample(iNumBurnupIterations, iNumCollectIterations,
lambda x : numpy.exp( - x[:,0]**2 ),
Tasmanian.DREAM.Domain("unbounded"),
state,
Tasmanian.DREAM.IndependentUpdate("uniform", 0.5),
Tasmanian.DREAM.DifferentialUpdate(90))
```
See the Python examples in `<install-prefix>/share/Tasmanian/examples/`.
### Additional Documentation
Every class and method in Tasmanian comes with additional comments designed to be
accessed with the Python `help()` function, e.g.,
```
help(Tasmanian.SparseGrid.makeGlobalGrid)
```
* Sparse grid module and C++ equivalent:
```
Tasmanian.SparseGrid (class) -> TasGrid::TasmanianSparseGrid (class)
Tasmanian.TasmanianSimpleSparseMatrix (class) -> triplet vectors (pntr, indx, vals)
```
* DREAM module and C++ equivalent:
```
import Tasmanian.DREAM as DREAM
(class) DREAM.State -> TasDREAM::TasmanianDREAM (class)
(class) DREAM.LikelihoodGaussIsotropic -> TasDREAM::LikelihoodGaussIsotropic (class)
(class) DREAM.LikelihoodGaussAnisotropic -> TasDREAM::LikelihoodGaussAnisotropic (class)
(class) DREAM.Posterior -> TasDREAM::posterior (method)
(method) DREAM.PosteriorEmbeddedLikelihood -> TasDREAM::posterior (method-overload)
(method) DREAM.genUniformSamples -> TasDREAM::genUniformSamples (method)
(method) DREAM.genGaussianSamples -> TasDREAM::genGaussianSamples (method)
(method) DREAM.Sample -> TasDREAM::SampleDREAM (method)
```
* Addon module methods and C++ equivalent:
```
Tasmanian.loadNeededValues -> TasGrid::loadNeededValues <overwrite_loaded=false>
Tasmanian.reloadLoadedValues -> TasGrid::loadNeededValues <overwrite_loaded=true>
Tasmanian.constructAnisotropicSurrogate -> TasGrid::constructSurrogate (anistropic overload)
Tasmanian.constructSurplusSurrogate -> TasGrid::constructSurrogate (surplus overload)
```
### Error Handling
The Tasmanian Python module comes with a comprehensive error checking mechanisms
where the validity of the inputs to every method are checked and `TasmanianInputError`
exception is raised whenever invalid input is encountered.
The `TasmanianInputError` class has two variables:
* **sVariable** indicates the variable with invalid input or the name of the method
if the method was called out of order, e.g., `evaluate()` cannot be called before `loadNeededPoints()`
* **sMessage** is a human readable string giving specific description to of the error.
### Acceleration and Thread Safety
All acceleration modes are available through the Python interface and the same
rules for thread safety apply as in the C++ interface.
One point of difference is the `SparseGrid.evaluate()` function, which on the Python side
will link to `SparseGrid.evaluateFast()` and therefore not safe to call from different threads.
Safe evaluations can be performed with `SparseGrid.evaluateThreadSafe()`.
The model callable inputs to load/reload and construct methods will be executed in
parallel on most Python implementations.
### Basic Plotting
If `matplotlib.pyplot` module is available, `Tasmanian.SparseGrid` will enable two plotting methods:
* **plotPoints2D()** plots the nodes associated with the grid
* **plotResponse2D()** plots a color image corresponding to the response surface
Both methods work only with two dimensional grids.
Note that `matplotlib.pyplot` doesn't have to be available during build time,
it can be installed later and still used with a current installation of Tasmanian.
|
