← Back to branch summary

~ubuntu-branches/ubuntu/karmic/python-scipy/karmic

« back to all changes in this revision

Viewing changes to Lib/sandbox/buildgrid/README.txt

  • Committer: Bazaar Package Importer
  • Author(s): Ondrej Certik
  • Date: 2008-06-16 22:58:01 UTC
  • mfrom: (2.1.24 intrepid)
  • Revision ID: james.westby@ubuntu.com-20080616225801-irdhrpcwiocfbcmt
Tags: 0.6.0-12
http://bugs.debian.org/489149
* The description updated to match the current SciPy (Closes: #489149).
* Standards-Version bumped to 3.8.0 (no action needed)
* Build-Depends: netcdf-dev changed to libnetcdf-dev

Show diffs side-by-side

added added

removed removed

Lines of Context:
Lib/sandbox/buildgrid/README.txt
1
 
    Build Grid,  Version 0.5, Jun 24, 2006
2
 
    --------------------------------------
3
 
    
4
 
Build regular grids from scattered 2D data.
5
 
Python extension module.
6
 
 
7
 
Summary
8
 
========  
9
 
Input:
10
 
    a set of arbitrary displaced points in 2D plane,
11
 
    grid geometry: x/y min/max and cell size, 
12
 
    a few (optional) control parameters 
13
 
 
14
 
Output:
15
 
    to a python list or to file
16
 
 
17
 
Method: 
18
 
    Put every input data point into nearest grid node (take average if more
19
 
    than one), this is main source of errors. Apply empirical method of 
20
 
    building: make sequence of averagings with full interpolation. Use 
21
 
    distances from data points to remove field values far from data points.
22
 
    The method is fair for large data volumes (and grid sizes). 
23
 
    The method is irrelevant if (x,y) must be treated as exact values,
24
 
    or the surface should have breaks or spikes of any kind.
25
 
    The surface has no special predefined properties like derivatives,
26
 
    curvatures, etc, but it is as smooth as possible in this approach.
27
 
 
28
 
 
29
 
Details
30
 
========
31
 
 
32
 
Installation:
33
 
    The module depends only on Python.h and standard python libraries.
34
 
    Compiled (as C, not C++) with MinGW Dev.Studio 2.05, MS VC++ 6.0,
35
 
    (Windows XP) and gcc-4 (ubuntu). To install on Windows one can just
36
 
    rename .dll to a directory on the path as BuildGrid.pyd. To compile 
37
 
    and install on Linux one can use setup.py. 
38
 
 
39
 
Tests:
40
 
    Python test script is BuildGrid_Test.py. To set/change test parameters
41
 
    see the script. There are two surfaces, first is almost a plane,
42
 
    second is like cos(a*x*x) to make it impossible to interpolate
43
 
    the surface at the far corners of grid. Some differences between
44
 
    built surface and exact surface are seen in terminal window.
45
 
    I used QuikGrid from http://www.PerspectiveEdge.com to see the
46
 
    results in contours and colors.
47
 
    On my laptop (1.6 Ghz) the module produces about 10**5 output nodes
48
 
    per second (without trimming, there is a weak dependence on input 
49
 
    data volume, precision, etc).
50
 
 
51
 
General Limitations:
52
 
    - minimal grid sizes in nodes: 9 (lesser has no sense in the method)
53
 
    - maximal grid sizes in nodes: about 10000 (currently 10915),
54
 
        that needs ~300 MB of memory to build
55
 
    - minimal cell size: 0.001 (hardcoded to avoid zero dividing)
56
 
    - all sizes, coordinates, distances should be in same units
57
 
    - at least one input triple (x,y,z) must be given
58
 
    - method is irrelevant when exact values of x and y must be used
59
 
        or the surface should have breaks or spikes of any kind
60
 
    - in grid nodes numeration, (0,0) is node with coordinates (xmin,ymin),
61
 
        x values and column numbers increase to East,
62
 
        y values and row numbers increase to North
63
 
    - output list of grid node values is indexed from bottom to top row,
64
 
        from left to right column in the rows
65
 
    - output data take at least 8*ncol*nrow bytes (double values),
66
 
        maximal memory consumption during the building is about 
67
 
        30*ncol*nrow bytes
68
 
 
69
 
Input data and parameters:
70
 
    - xyz-file of text lines with x,y,z values, space separated, or
71
 
    - lists of x,y,z data. Lists are separate for x, y, z data. 
72
 
      No special order of (x,y,z) triples is supposed for input data. 
73
 
    - grid boundaries are set from (xmin,ymin), (square) cell size (step)
74
 
      and grid sizes in nodes.
75
 
    - grid building method: 'Good' (default) or 'Best' (not implemented)
76
 
    - acceptable error level - absolute or relative. Default is 0.0 (Note:
77
 
      it is not an 'interpolation'). If absolute error value > 0.0, it will
78
 
      be used, otherwise if relative error value > 0.0, then it will be
79
 
      used, otherwise error will be equal to (almost) 0.0.  Relative error
80
 
      value is used as fraction of input data standard deviation.
81
 
    - trimming distance: throw out (i.e. replace by non-values) all the 
82
 
      values with distances from sources larger than trimdistance, starting 
83
 
      from grid boundaries (i.e. internal nodes may be untouched). This
84
 
      parameter is ignored if its value < step.
85
 
    - unvalue, use for output, to mark nodes without values (default: 12345678.9)
86
 
 
87
 
Python interface (registered functions):
88
 
 
89
 
    filestatistics(xyzfilename)
90
 
        The file is a sequence of text lines, each with x,y,z values,
91
 
        separated by spaces. 
92
 
                Return (number_of_values, 
93
 
                x_minimum, x_maximum, y_minimum, y_maximum, 
94
 
                s_minimum, s_maximum, s_average, s_standard)
95
 
                Raise IOError -- could not open file.
96
 
    
97
 
 
98
 
    fromfile(
99
 
        xyzfile=filename,       - input file of text lines: x y z
100
 
                nx=xnodes, ny=ynodes,   - grid sizes in nodes
101
 
                step=cellsize,          - cell sizes, cells are square
102
 
                xmin=minX, ymin=minY,   - left bottom, x - east, y - north
103
 
        # Optional parameters:
104
 
                method='Good',          - or 'Best' (not implemented)
105
 
                trimming=trimdistance,  - distance to trim, ignored if trimming < step
106
 
                unvalue=non_value,      - caller unvalue, ignored if no trimming
107
 
        abserror=AbsError,      - acceptable error if > 0
108
 
        relerror=RelError,      - the same, ignored if abserror > 0.0
109
 
                                  is fraction of standard (if abserror==0)
110
 
                )
111
 
        Return grid as list, rows from bottom, columns from left
112
 
                Raise ValueError/IOError for errors with file/memory
113
 
    
114
 
   fromxyz(
115
 
        xdata=x, ydata=y, zdata=z, - lists of input data (of same length)
116
 
                nx=xnodes, ny=ynodes,
117
 
                step=cellsize,       
118
 
                xmin=minX, ymin=Ymin,
119
 
        # Optional parameters are the same as for fromfile()
120
 
                method='Good',         
121
 
                trimming=trimdistance, 
122
 
                unvalue=non_value,    
123
 
        abserror=AbsError,    
124
 
        relerror=RelError,    
125
 
        )
126
 
                Return grid as list, rows from bottom, columns from left
127
 
                Raise ValueError/IOError for errors with values/memory
128
 
        
129
 
   tofile(
130
 
        outfile=filename,       - output file name
131
 
                griddata=xyz,           - list as returned by fromfile() or fromxyz()
132
 
                nx=xnodex, ny=ynodes,   - grid sizes in nodes
133
 
        filetype=grid_type,     - 'xyz' ('gxf'/'grd'/... not implemented) 
134
 
        # Optional parameters:
135
 
                step=cellsize,          - cell sizes, default: 1.0
136
 
                xmin=minX, ymin=Ymin,   - left bottom, x - east, y - north
137
 
                                - default: xmin=ymin=0.0
138
 
                unvalue=non_value,      - caller unvalue, default: 12345678.9
139
 
                                - grid nodes with unvalue will not be put to 'xyz' file
140
 
        )
141
 
                Return 0 for Ok
142
 
                Raise ValueError/IOError for errors with file/memory
143
 
 
144
 
ToDo:
145
 
    The module can be extended and improved in some directions:
146
 
    - more accurate calculations of errors in grid nodes - try to
147
 
        reach limits in each given node
148
 
    - more precise computing input data in nodes (add mrrgins, decrease cells)
149
 
    - various input/output data formats
150
 
    - more information about input and intermediate data
151
 
    - the same method can be used to build 3D grids, s(x,y,z,...)
152
 
 
153
 
Eugene Druker, 2006 
154
 
eugene.druker@gmail.com
155