BCLS: Bound Constrained Least Squares

Version 0.1

bcls.h

Go to the documentation of this file.
00001 /* bcls.h
00002    $Revision: 276 $ $Date: 2006-12-09 21:00:00 -0800 (Sat, 09 Dec 2006) $
00003 
00004    ----------------------------------------------------------------------
00005    This file is part of BCLS (Bound-Constrained Least Squares).
00006 
00007    Copyright (C) 2006 Michael P. Friedlander, Department of Computer
00008    Science, University of British Columbia, Canada. All rights
00009    reserved. E-mail: <mpf@cs.ubc.ca>.
00010    
00011    BCLS is free software; you can redistribute it and/or modify it
00012    under the terms of the GNU Lesser General Public License as
00013    published by the Free Software Foundation; either version 2.1 of the
00014    License, or (at your option) any later version.
00015    
00016    BCLS is distributed in the hope that it will be useful, but WITHOUT
00017    ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
00018    or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU Lesser General
00019    Public License for more details.
00020    
00021    You should have received a copy of the GNU Lesser General Public
00022    License along with BCLS; if not, write to the Free Software
00023    Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301
00024    USA
00025    ----------------------------------------------------------------------
00026 */
00033 #ifndef _BCLS_H
00034 #define _BCLS_H
00035 
00036 /* Prevent C++ programs from name mangling these definitions. */
00037 #ifdef __cplusplus
00038 extern "C" {
00039 #endif
00040 
00041 #include <stdio.h>
00042 #include <setjmp.h>
00043 #include "bctimer.h"
00044 
00045 /* The BCLS objects define everything about a problem. */
00046 typedef struct BCLS BCLS;
00047 struct BCLS {
00048 
00050     void *print_info;
00051 
00053     int (*print_hook)(void *info, char *msg);
00054 
00056     void *fault_info;
00057 
00059     int (*fault_hook)(void *info, char *msg);
00060 
00062     int (*Aprod)( int mode, int m, int n, int nix,
00063                   int ix[], double x[], double y[], void *UsrWrk );
00064 #define BCLS_PROD_A     1 
00065 #define BCLS_PROD_At    2 
00066 #define BCLS_PROD_INIT -1 
00067 #define BCLS_PROD_TERM -2 
00070     int (*Usolve)( int mode, int m, int n, int nix,
00071                    int ix[], double v[], double w[], void *UsrWrk );
00072 #define BCLS_PRECON_U     1 
00073 #define BCLS_PRECON_Ut    2 
00074 #define BCLS_PRECON_INIT -1 
00075 #define BCLS_PRECON_TERM -2 
00078     int (*CallBack)( BCLS *ls, void *UsrWrk );
00079 
00081     double *anorm;
00082 #define BCLS_MIN_COLUMN_NORM  1e-8 
00085     void *UsrWrk;
00086 
00087     /* User options. */
00088     int print_level;               
00089     int proj_search;               
00090 #define BCLS_PROJ_SEARCH_EXACT   0 
00091 #define BCLS_PROJ_SEARCH_APPROX  1 
00092     int newton_step;               
00093 #define BCLS_NEWTON_STEP_LSQR    0 
00094 #define BCLS_NEWTON_STEP_CGLS    1 
00095     FILE *minor_file;              
00098     BCLS_timer stopwatch[4];
00099 #define BCLS_TIMER_TOTAL   0 
00100 #define BCLS_TIMER_APROD   1 
00101 #define BCLS_TIMER_LSQR    2 
00102 #define BCLS_TIMER_USOLVE  3 
00104     /* Counters (iterations, no. of mat-vecs calls, etc.) */
00105     int itnMaj;     
00106     int itnMajLim;  
00107     int itnMin;     
00108     int itnMinLim;  
00109     int nAprodT;    
00110     int nAprodF;    
00111     int nAprod1;    
00112     int nUsolve;    
00115     int m;
00116 
00118     int n;
00119 
00121     int mmax;
00122 
00124     int nmax;
00125 
00127     int unconstrained;
00128 
00129     /* Damping parameters. */
00130     double damp;            
00131     double damp_min;        
00132     double damp_actual;     
00135     int exit;
00136 #define BCLS_EXIT_CNVGD    0 
00137 #define BCLS_EXIT_MAJOR    1 
00138 #define BCLS_EXIT_MINOR    2 
00139 #define BCLS_EXIT_UNDEF    3 
00140 #define BCLS_EXIT_UNBND    4 
00141 #define BCLS_EXIT_INFEA    5 
00142 #define BCLS_EXIT_LFAIL    6 
00143 #define BCLS_EXIT_APROD  100 
00144 #define BCLS_EXIT_USOLVE 110 
00145 #define BCLS_EXIT_CALLBK 120 
00147     /* Status of the solution (stored in x). */
00148     double soln_obj;       
00149     double soln_rNorm;     
00150     double soln_dInf;      
00151     int    soln_jInf;      
00152     int    soln_stat;      
00153 #define BCLS_SOLN_UNDEF  0 
00154 #define BCLS_SOLN_OPTIM  1 
00156     /* Tolerances and limits. */
00157     double optTol;          
00158     double conlim;          
00159     double mu;              
00160     double backtrack;       
00161     int    backtrack_limit; 
00163     /* Constants. */
00164     double eps;             
00165     double eps2;            
00166     double eps3;            
00167     double epsx;            
00168     double epsfixed;        
00169     double BigNum;          
00170 #define BCLS_INFINITY 1e+20
00171 
00173     double *x;
00174 
00176     double *b;
00177 
00179     double *c;
00180 
00182     double *bl;
00183 
00185     double *bu;
00186 
00187     /* BCLS workspace (allocated by BCLS). */
00188     double *r;              
00189     double *g;              
00190     double *dx;             
00191     double *dxFree;         
00192     double *aBreak;         
00193     int    *iBreak;         
00194     int    *ix;             
00195     double *wrk_u;          
00196     double *wrk_v;          
00197     double *wrk_w;          
00200     jmp_buf jmp_env;
00201 
00202 };
00203 
00204 /* Create a new BCLS problem. */
00205 BCLS *
00206 bcls_create_prob( int mmax, int nmax );
00207 
00208 /* Initialize  a new BCLS problem. */
00209 void
00210 bcls_init_prob( BCLS *ls );
00211 
00212 /* Free a BCLS problem. */
00213 int
00214 bcls_free_prob( BCLS *ls );
00215 
00216 /* Return an exit message. */
00217 char *
00218 bcls_exit_msg( int flag );
00219 
00220 /* Driver for the BCLS solver. */
00221 int
00222 bcls_solve_prob( BCLS *ls );
00223 
00224 /* Install a user-defined print-hook routine. */
00225 void
00226 bcls_set_print_hook( BCLS *ls, void *info,
00227                      int (*hook)(void *info, char *msg) );
00228 
00229 /* Install a user-defined print-hook routine. */
00230 void
00231 bcls_set_fault_hook( BCLS *ls, void *info,
00232                      int (*hook)(void *info, char *msg) );
00233 
00234 /* Install a user-defined preconditioning routine. */
00235 void
00236 bcls_set_usolve( BCLS *ls,
00237                  int (*Usolve)( int mode, int m, int n, int nix,
00238                                 int ix[], double v[], double w[],
00239                                 void *UsrWrk ) );
00240 
00241 /* Give BCLS access to a set of column norms of A. */
00242 void
00243 bcls_set_anorm( BCLS *ls, double anorm[] );
00244 
00245 /* Compute column norms of A. */
00246 int
00247 bcls_compute_anorm( BCLS *ls, int n, int m,
00248                     int (*Aprod)
00249                     ( int mode, int m, int n, int nix,
00250                       int ix[], double x[], double y[], void *UsrWrk ),
00251                     void *UsrWrk,
00252                     double anorm[] );
00253 
00254 /* Set the problem data. */
00255 void
00256 bcls_set_problem_data( 
00257      BCLS  *ls,    /* A BCLS problem */
00258      int    m,     /* No. of problem rows */
00259      int    n,     /* No. of problem columns */
00260      int (*Aprod)  /* Matrix-vector product routine */
00261          ( int mode, int m, int n, int nix,
00262            int ix[], double x[], double y[], void *UsrWrk ),
00263      void  *UsrWrk,/* Arbitrary user data passed to Aprod */
00264      double damp,  /* The damping parameter */
00265      double x[],   /* The solution vector (n) */
00266      double b[],   /* The RHS vector (m) */
00267      double c[],   /* The linear term (n) */
00268      double bl[],  /* The lower bounds vector */
00269      double bu[]   /* The upper bounds vector */
00270      );
00271                          
00272 #ifdef __cplusplus
00273 }
00274 #endif
00275 
00276 #endif /* _BCLS_H */

Generated on Sun Mar 4 22:50:03 2007 by Doxygen 1.5.1