source: inundation/wiki/least_squares_refactoring.txt @ 1918

Last change on this file since 1918 was 1918, checked in by duncan, 18 years ago

update

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