1 | Project Plan |
---|
2 | |
---|
3 | By Duncan Gray |
---|
4 | |
---|
5 | INTRODUCTION |
---|
6 | |
---|
7 | Software, called least squares, has been developed to implement a |
---|
8 | penalised least-squares fit and associated interpolations. It is in |
---|
9 | least_squares.py. Steven Roberts outlined the least squares algorithm |
---|
10 | used. The code is currently not meeting user requirements with |
---|
11 | regards to speed and memory use. Additional functionality is also needed. |
---|
12 | |
---|
13 | SCOPE |
---|
14 | This is looking at refactoring the Class Interpolation and the |
---|
15 | functions fit_to_mesh_file, fit_to_mesh and the command line use of |
---|
16 | least_squares.py. |
---|
17 | |
---|
18 | LIFE-CYCLE |
---|
19 | |
---|
20 | Use a staged delivery life-cycle (see rapid development), with the |
---|
21 | proviso that additional functionality to supporting objects, such as |
---|
22 | build_quadtree in quad.py can be worked on after requirements have |
---|
23 | been determined. Also, the current least squares may be tinkered with |
---|
24 | to check the feasibility of concepts and general maintanance. The |
---|
25 | main thrust will be refactoring though. |
---|
26 | |
---|
27 | |
---|
28 | ______________________________________________________________________ |
---|
29 | Least Squares Refactoring Software Requirements Specification |
---|
30 | |
---|
31 | By Duncan Gray |
---|
32 | |
---|
33 | |
---|
34 | INTRODUCTION |
---|
35 | |
---|
36 | This document specifies the requirements to implement least squares |
---|
37 | is refactored. |
---|
38 | |
---|
39 | DEFINITIONS |
---|
40 | |
---|
41 | |
---|
42 | REQUIREMENT SECTION |
---|
43 | |
---|
44 | Introduction |
---|
45 | |
---|
46 | Assume that all the requirements of the current least squares code will |
---|
47 | stay the same, unless stated. Note implementation and names used are |
---|
48 | not regarded as requirements. |
---|
49 | |
---|
50 | |
---|
51 | Requirements |
---|
52 | |
---|
53 | When interpolating, return information on which points were outside |
---|
54 | the mesh (in such a way that it can not be interporated as real data). |
---|
55 | If attribute information for points outside the mesh is returned, that can |
---|
56 | only be a float, let the user set the default value that is returned |
---|
57 | for points outside the mesh. |
---|
58 | |
---|
59 | When fitting, when in verbose mode display how many triangles are in the |
---|
60 | mesh and how many are out. Also display the max # of points/ triangle |
---|
61 | and the minimum number of points. If this operation takes alot of |
---|
62 | time, let it be optional. |
---|
63 | |
---|
64 | Warn the user when fitting to mesh if the mesh is outside the points boundary. |
---|
65 | (Note: by using alpha least squares can always return a result in this |
---|
66 | situation) |
---|
67 | |
---|
68 | Fitting 5 million points to a one million triangles mesh will not cause a |
---|
69 | memory error. |
---|
70 | |
---|
71 | Reduce the time spent building matrix A. (not a testable requirement) |
---|
72 | |
---|
73 | (This isn't long, are there any other requirements?) |
---|
74 | |
---|
75 | Requirement Notes |
---|
76 | How should we handle points outside of the mesh when interpolating? |
---|
77 | Currently the interpolated values are set to 0.0. |
---|
78 | Other options are, set to a given value. |
---|
79 | Raise an error. |
---|
80 | Raise/return a warning and set to a given value/0.0. (I like this one) |
---|
81 | |
---|
82 | |
---|
83 | How should interpolate_sww respond? |
---|
84 | warning/error/exit/replace with given value. |
---|
85 | |
---|
86 | General Error Handling Guidelines |
---|
87 | |
---|
88 | Assume 4 ways of using the code (for Inperpolate class) |
---|
89 | 1) command line interface |
---|
90 | 2) API function - these have parameters of input data file names, |
---|
91 | output file names, and carry out a process. |
---|
92 | 3) External methods - These are the calls that the api function uses |
---|
93 | 4) Internal methods. |
---|
94 | |
---|
95 | Way 1 is used by general users, so they should not return |
---|
96 | something that looks like a code crash from bad input. |
---|
97 | An option for way 2 is to raise an exception, which the user |
---|
98 | handles. Should the code display a warning, based on the error? |
---|
99 | |
---|
100 | Note, if a method is used by a gui, or by scripts change the requirements |
---|
101 | Discus with Error Handling Ole |
---|
102 | |
---|
103 | |
---|
104 | ___________________________________________________________________________ |
---|
105 | Least Squares System Design Specification |
---|
106 | |
---|
107 | By Duncan Gray - lots of good ideas by Ole |
---|
108 | |
---|
109 | |
---|
110 | INTRODUCTION |
---|
111 | |
---|
112 | This specifies design choices for the least squares code. |
---|
113 | |
---|
114 | DESIGN IDEAS, to meet requirements |
---|
115 | *To save memory; |
---|
116 | When interpolating, don't build AtA, B and D. (This has been implemented) |
---|
117 | When fitting, don't build A. - Work with AtA and Atz. |
---|
118 | |
---|
119 | |
---|
120 | |
---|
121 | |
---|
122 | * To save memory |
---|
123 | |
---|
124 | This is for the layer interpolation and fitting with IO: Use blocking |
---|
125 | when interpolating/fitting a large number of points (how large? Can the |
---|
126 | program check the available memory and work out a good block size?) |
---|
127 | |
---|
128 | The code has to be refactored so fitting can handling blocked point |
---|
129 | info. Need a building phase and a solve phase. |
---|
130 | |
---|
131 | |
---|
132 | *To reduce the time spent building matrix A. |
---|
133 | |
---|
134 | Change the expansion algorithm, when determining what triangle a point |
---|
135 | is in, when none of the vertices are in the cell the point is in. |
---|
136 | |
---|
137 | Options (still thinking about this one) |
---|
138 | * It should look in the cell of the point and then all adjacent |
---|
139 | cells. If it isn't there then ... we have problems. My feeling is it |
---|
140 | has to be there. |
---|
141 | - Building the structure to keep this info could be prohibative. |
---|
142 | |
---|
143 | |
---|
144 | Another speed up option is to write the bottlenecks in C. Do it if necessary. |
---|
145 | |
---|
146 | |
---|
147 | DESIGN IDEAS, refactoring |
---|
148 | |
---|
149 | Remove georeferencing from build_interpolation_matrix_A. Change the |
---|
150 | point co-ords to conform to the mesh co-ords early in the code. |
---|
151 | |
---|
152 | Currently there is one class, called Interpolation, that holds the |
---|
153 | matrix data and methods for fitting and interpolation. Break this |
---|
154 | into two classes, one for fittting, the other for interpolation. Have |
---|
155 | processes common to both classes in functions. |
---|
156 | |
---|
157 | Have least squares as two stand alone packages. One that has the guts |
---|
158 | of LS (e.g. the two new classes). One that is has the IO API's |
---|
159 | (functions that load and write files). The guts package will be |
---|
160 | dependent of the general mesh package. The IO API will rely on an IO |
---|
161 | module. |
---|
162 | |
---|
163 | HOW WILL IMPLEMENTATION OCCUR? |
---|
164 | Code a new least squares module in a seperate directory. Heavily cut |
---|
165 | and paste from the old least squares. Implement memory and time tests |
---|
166 | on the old least squares (and new LS) before doing any changes. |
---|