BCLS: Bound Constrained Least Squares

Version 0.1

bcls.h

Go to the documentation of this file.

/* bcls.h
   $Revision: 276 $ $Date: 2006-12-09 21:00:00 -0800 (Sat, 09 Dec 2006) $

   ----------------------------------------------------------------------
   This file is part of BCLS (Bound-Constrained Least Squares).

   Copyright (C) 2006 Michael P. Friedlander, Department of Computer
   Science, University of British Columbia, Canada. All rights
   reserved. E-mail: <mpf@cs.ubc.ca>.
   
   BCLS is free software; you can redistribute it and/or modify it
   under the terms of the GNU Lesser General Public License as
   published by the Free Software Foundation; either version 2.1 of the
   License, or (at your option) any later version.
   
   BCLS is distributed in the hope that it will be useful, but WITHOUT
   ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
   or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU Lesser General
   Public License for more details.
   
   You should have received a copy of the GNU Lesser General Public
   License along with BCLS; if not, write to the Free Software
   Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301
   USA
   ----------------------------------------------------------------------
*/
#ifndef _BCLS_H
#define _BCLS_H

/* Prevent C++ programs from name mangling these definitions. */
#ifdef __cplusplus
extern "C" {
#endif

#include <stdio.h>
#include <setjmp.h>
#include "bctimer.h"

/* The BCLS objects define everything about a problem. */
typedef struct BCLS BCLS;
struct BCLS {

    void *print_info;

    int (*print_hook)(void *info, char *msg);

    void *fault_info;

    int (*fault_hook)(void *info, char *msg);

    int (*Aprod)( int mode, int m, int n, int nix,
                  int ix[], double x[], double y[], void *UsrWrk );
#define BCLS_PROD_A     1 
#define BCLS_PROD_At    2 
#define BCLS_PROD_INIT -1 
#define BCLS_PROD_TERM -2 
    int (*Usolve)( int mode, int m, int n, int nix,
                   int ix[], double v[], double w[], void *UsrWrk );
#define BCLS_PRECON_U     1 
#define BCLS_PRECON_Ut    2 
#define BCLS_PRECON_INIT -1 
#define BCLS_PRECON_TERM -2 
    int (*CallBack)( BCLS *ls, void *UsrWrk );

    double *anorm;
#define BCLS_MIN_COLUMN_NORM  1e-8 
    void *UsrWrk;

    /* User options. */
    int print_level;               
    int proj_search;               
#define BCLS_PROJ_SEARCH_EXACT   0 
#define BCLS_PROJ_SEARCH_APPROX  1 
    int newton_step;               
#define BCLS_NEWTON_STEP_LSQR    0 
#define BCLS_NEWTON_STEP_CGLS    1 
    FILE *minor_file;              
    BCLS_timer stopwatch[4];
#define BCLS_TIMER_TOTAL   0 
#define BCLS_TIMER_APROD   1 
#define BCLS_TIMER_LSQR    2 
#define BCLS_TIMER_USOLVE  3 
    /* Counters (iterations, no. of mat-vecs calls, etc.) */
    int itnMaj;     
    int itnMajLim;  
    int itnMin;     
    int itnMinLim;  
    int nAprodT;    
    int nAprodF;    
    int nAprod1;    
    int nUsolve;    
    int m;

    int n;

    int mmax;

    int nmax;

    int unconstrained;

    /* Damping parameters. */
    double damp;            
    double damp_min;        
    double damp_actual;     
    int exit;
#define BCLS_EXIT_CNVGD    0 
#define BCLS_EXIT_MAJOR    1 
#define BCLS_EXIT_MINOR    2 
#define BCLS_EXIT_UNDEF    3 
#define BCLS_EXIT_UNBND    4 
#define BCLS_EXIT_INFEA    5 
#define BCLS_EXIT_LFAIL    6 
#define BCLS_EXIT_APROD  100 
#define BCLS_EXIT_USOLVE 110 
#define BCLS_EXIT_CALLBK 120 
    /* Status of the solution (stored in x). */
    double soln_obj;       
    double soln_rNorm;     
    double soln_dInf;      
    int    soln_jInf;      
    int    soln_stat;      
#define BCLS_SOLN_UNDEF  0 
#define BCLS_SOLN_OPTIM  1 
    /* Tolerances and limits. */
    double optTol;          
    double conlim;          
    double mu;              
    double backtrack;       
    int    backtrack_limit; 
    /* Constants. */
    double eps;             
    double eps2;            
    double eps3;            
    double epsx;            
    double epsfixed;        
    double BigNum;          
#define BCLS_INFINITY 1e+20

    double *x;

    double *b;

    double *c;

    double *bl;

    double *bu;

    /* BCLS workspace (allocated by BCLS). */
    double *r;              
    double *g;              
    double *dx;             
    double *dxFree;         
    double *aBreak;         
    int    *iBreak;         
    int    *ix;             
    double *wrk_u;          
    double *wrk_v;          
    double *wrk_w;          
    jmp_buf jmp_env;

};

/* Create a new BCLS problem. */
BCLS *
bcls_create_prob( int mmax, int nmax );

/* Initialize  a new BCLS problem. */
void
bcls_init_prob( BCLS *ls );

/* Free a BCLS problem. */
int
bcls_free_prob( BCLS *ls );

/* Return an exit message. */
char *
bcls_exit_msg( int flag );

/* Driver for the BCLS solver. */
int
bcls_solve_prob( BCLS *ls );

/* Install a user-defined print-hook routine. */
void
bcls_set_print_hook( BCLS *ls, void *info,
                     int (*hook)(void *info, char *msg) );

/* Install a user-defined print-hook routine. */
void
bcls_set_fault_hook( BCLS *ls, void *info,
                     int (*hook)(void *info, char *msg) );

/* Install a user-defined preconditioning routine. */
void
bcls_set_usolve( BCLS *ls,
                 int (*Usolve)( int mode, int m, int n, int nix,
                                int ix[], double v[], double w[],
                                void *UsrWrk ) );

/* Give BCLS access to a set of column norms of A. */
void
bcls_set_anorm( BCLS *ls, double anorm[] );

/* Compute column norms of A. */
int
bcls_compute_anorm( BCLS *ls, int n, int m,
                    int (*Aprod)
                    ( int mode, int m, int n, int nix,
                      int ix[], double x[], double y[], void *UsrWrk ),
                    void *UsrWrk,
                    double anorm[] );

/* Set the problem data. */
void
bcls_set_problem_data( 
     BCLS  *ls,    /* A BCLS problem */
     int    m,     /* No. of problem rows */
     int    n,     /* No. of problem columns */
     int (*Aprod)  /* Matrix-vector product routine */
         ( int mode, int m, int n, int nix,
           int ix[], double x[], double y[], void *UsrWrk ),
     void  *UsrWrk,/* Arbitrary user data passed to Aprod */
     double damp,  /* The damping parameter */
     double x[],   /* The solution vector (n) */
     double b[],   /* The RHS vector (m) */
     double c[],   /* The linear term (n) */
     double bl[],  /* The lower bounds vector */
     double bu[]   /* The upper bounds vector */
     );
                         
#ifdef __cplusplus
}
#endif

#endif /* _BCLS_H */

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