https://github.com/ralna/galahad

A library of modern Fortran modules for nonlinear optimization
https://github.com/ralna/galahad

c cubic-regularization-methods fortran julia mathematical-programming matlab nonlinear-least-squares nonlinear-optimization numerical-optimization python quadratic-programming trust-region-methods

Last synced: about 18 hours ago
JSON representation

A library of modern Fortran modules for nonlinear optimization

• Host: GitHub
• URL: https://github.com/ralna/galahad
• Owner: ralna
• License: other
• Created: 2018-02-03T14:35:55.000Z (almost 7 years ago)
• Default Branch: master
• Last Pushed: 2024-10-29T20:03:54.000Z (3 months ago)
• Last Synced: 2024-10-29T22:40:39.893Z (3 months ago)
• Topics: c, cubic-regularization-methods, fortran, julia, mathematical-programming, matlab, nonlinear-least-squares, nonlinear-optimization, numerical-optimization, python, quadratic-programming, trust-region-methods
• Language: Fortran
• Homepage: https://www.galahad.rl.ac.uk
• Size: 179 MB
• Stars: 117
• Watchers: 7
• Forks: 15
• Open Issues: 6
• Metadata Files:
  • Readme: README
  • License: LICENSE

Awesome Lists containing this project

README

        
In order to get GALAHAD working, here is what you need to do.

    ===========

    PREPARATION

    ===========

[-1. If you are hoping for advice about installing GALAHAD

   under Windows, see README.windows. If this isn't what you wanted,

   try Dilipan Sebastiampillai's document lanb2win.pdf.]

0. You will definitely need the package auxiliary package ARCHDefs.

   If you plan to use GALAHAD to solve problems written as .SIF

   files, you will also need the package SiFDec. If, in addition,

   you plan to use the CUTEst interfaces to the GALAHAD FILTRANE, QP,

   least-squares, regularization and/or unconstrained minimization routines,

   you will also need the package CUTEst. See

     https://github.com/ralna/CUTEst/wiki

   for details of how to obtain these. CUTEst is not necessary if you simply

   wish to use LANCELOT B to solve problems written as .SIF files.

   You should download the necessary packages ARCHDefs, SIFDecode and

   CUTEst as described in the above Wiki, and set the environment variables

   $ARCHDEFS, $SIFDECODE and $CUTEST as described - (see steps 0 and 1 in the

   README that comes with SIFDecode/CUTEst for more details - i.e.,

   for the C shell (csh):

    setenv ARCHDEFS [full path to ./archdefs directory]

    setenv SIFDECODE [full path to ./sifdecode directory]

    setenv CUTEST [full path to ./cutest directory]

   for the bourne again shell (bash)

    export ARCHDEFS=[full path to ./archdefs directory]

    export SIFDECODE=[full path to ./sifdecode directory]

    export CUTEST=[full path to ./cutest directory]

   ** NOTE THAT YOU DO NOT NEED TO INSTALL THESE PACKAGES, AS THE GALAHAD

      INSTALLATION WILL DO THIS FOR YOU IN A PROPERLY-INTEGRATED WAY **

   If you plan to use the AMPL interface, you must have installed a working

   version of the AMPL interface library, see

     ftp://netlib.bell-labs.com/netlib/ampl/solvers.tar

   This is not needed if you simply wish to use the GALAHAD packages

   stand-alone or via the CUTEst/SIF interface.

   There are now C interfaces to a large subset of GALAHAD packages.

   See README.C for more details if you want this functionality.

[ 1. Do yourself a favour ... get GNU make:

      http://www.gnu.org/software/make/make.html !

   GALAHAD is designed to be installed by any variant of the make

   program that we are aware of, but such are the incompatibilities

   introduced by different vendors, we cannot be sure that make

   will work properly on your system. However, if you have

   GNU make (sometimes known as gmake), we have high confidence that

   your installation will be trouble free. Fortunately GNU make is the

   defualt version of make available with most modern operating systems]

2. *- Skip this step if GALAHAD has been downloaded directly using svn or git -*

   Put the file

     galahad.tar.gz

   in a suitable directory for which the ./galahad

   directory will be a sub-directory.

2. *- Skip this step if GALAHAD has been downloaded directly using svn or git -*

   Issue the command

     tar xzvf galahad.tar.gz]

4. Set the environment variable GALAHAD to point at the

   ./galahad directory, i.e.,

   for the C shell (csh):

    setenv GALAHAD [full path to ./galahad directory]

   for the bourne again shell (bash)

    export GALAHAD=[full path to ./galahad directory]

   Make this a permanent setting by inserting this command

   in your in your .cshrc/.bashrc file (or whichever shell resource file

   is appropriate for you) and "source" the file. See

   ./galahad/doc/README.cshrc and ./galahad/doc/README.bashrc for

   more details.

5. Preferably you should also download a subset of the HSL Archive packages,

   ad02, ma27 and ma33, that are highly useful to GALAHAD. This is *NOT*

   open source software, but the packages are available as a bundle,

   WITHOUT CHARGE, by registering at

     http://www.hsl.rl.ac.uk/download/hslarchive-galahad/latest

   You will need to provide a valid email address, and once you have

   registered you will be sent an email message providing a link

   to the software as a file in either zip or tar.gz format.

   Once you have downloaded this file, it should be uncompressed

   in the directory ./  (The destination can be changed by editing the

   environment variable $HSL_ARCHIVE in the file

     $GALAHAD/src/makedefs/packages.default

   see 8 below.)

   Without these codes, your choice of key linear equation solvers is

   severly restricted. In particular, if the default solver, ssids, is

   not supported by yur compiler, you will be forced to use LAPACk

   routines, and these may limit the size of problems that can be

   solved.

6. If you are intending to use the AMPL interface, set the environment

   variable AMPLDIR to point to the directory in which you have installed

   the AMPL interface library i.e.,

    setenv AMPLDIR [full path to the AMPL interface library directory]

   for the bourne again shell (bash)

    export AMPLDIR=[full path to the AMPL interface library directory]

   Make this a permanent setting by inserting this command

   in your in your .cshrc/.bashrc file (or whichever shell resource file

   is appropriate for you) and "source" the file. Again, see

   ./galahad/doc/README.cshrc and ./galahad/doc/README.bashrc for

   more details.

   [ -*-NB-*- If you plan to use AMPL with the Lahey lf95, Fujistu frt or

      Intel ifort compiler, change

      extern void MAIN__( VOID );

    to

      extern int MAIN__( int, char** );

    ( *note* the double underscore)

    somewhere around line 790 in $AMPLDIR/asl.h, as otherwise there will be

    clashes between GALAHAD and AMPL C interfaces ]

    Details on how to obtain demo (problem-size limited) or full versions

    of AMPL are given in

      https://ampl.com/try-ampl/download-a-free-demo/

7. Add the directory

     $GALAHAD/bin

   to your search path (preferably in your .cshrc or similar

   file) so that you will be able to use the GALAHAD/CUTEst

   interfaces. Again, see ./galahad/doc/README.cshrc or

   ./galahad/doc/README.bashrc for more details.

8. On installation the file

     $GALAHAD/src/makedefs/packages.default

    will be copied to

     $GALAHAD/src/makedefs/packages

   Before installation, you can examine (and edit if you wish) the

   file to see how you might provide the source code for additional

   external third-party packages, and to find instructions on how to

   get them and where to put them.

   ================ IMPORTANT NEWS FOR POTENTIAL HSL USERS ==============

   All the optional HSL software used by GALAHAD is available as a single

   tar.gz or gzip file. These files may be DOWNLOADED WITHOUT CHARGE FOR

   PERSONAL USE by any academic with a recognised academic email address.

   See

       http://www.hsl.rl.ac.uk/download/hsl-galahad/latest/d/

   (or  http://www.hsl.rl.ac.uk/download/hsl-galahad/latest/s/ for a

   single precision version) for registration details. Once you have

   registered you will be sent an email message providing a link

   to the software as a file in either zip or tar.gz format; there may

   be a delay in receiving the file, as it has to manually authorized

   by the HSL manager.

   Once you have downloaded this file, it should be uncompressed in a

   convenient location, and we recommend that you choose the directory ./

   ** N.B. The file ./galahad/src/makedefs/packages.default

   ** MUST BE EDITED ** to activate the HSL packages.

   Once GALAHAD has been installed, any further changes to optional

   software should be recorded in the file ./galahad/src/makedefs/packages,

   and GALAHAD recompiled so that the changes take effect (see 14 below).

9. You may also optionally provide binary code for a number of external

   packages that might make GALAHAD run faster. These include the

   BLAS ((basic linear algebra subprograms), LAPACK, MeTiS, PARDISO,

   MKL PARDISO, PASTIX, MUMPS and  WSMP.  Don't worry if you cannot provide

   thses; GALAHAD will compile non-optimised versions of the necessary ones

   (BLAS, LAPACK) and provide dummy versions of the others. See

   ./galahad/doc/README.external for more details.

10. If you plan to use the (limited) Matlab interfaces, make sure that

   the MATLAB environment variable points to your system Matlab directory,

   and that $GALAHAD/src/matlab is on your Matlab path. See README.matlab

   for more details.

11 If you are running on a Linux/OSX system, you may need to install the

   Open-MPI Portable Hardware Locality (HWLOC) development package

      https://www.open-mpi.org/projects/hwloc/

   This is readily available in many Linux distributions, e.g., via

      sudo apt-get install libhwloc-dev

   on Debian/Ubuntu systems,

      sudo rpm --install libhwloc-dev

   for Redhat ones, or

      brew install hwloc

   for Macs under OSX.

   You will also need to set environment variables  OMP_CANCELLATION,

   OMP_NESTED and OMP_PROC_BIND to TRUE, and OMP_MAX_ACTIVE_LEVEL to

   the maximum number of parallel threads you wish to use.

   Under the sh/bash shell, put

     export OMP_CANCELLATION=true

     export OMP_NESTED=true

     export OMP_PROC_BIND=true

     export OMP_MAX_ACTIVE_LEVELS=8

   in your startup script, to use a maximum of 8 threads, and for csh/tcsh

     setenv OMP_CANCELLATION true

     setenv OMP_NESTED true

     setenv OMP_PROC_BIND true

     setenv OMP_MAX_ACTIVE_LEVELS 8

   Check with your system administrator if you need help!

   If it *really* is impossible to install libhwloc-dev, you should edit

   the file $GALAHAD/src/spral/config.h and replace the line

   #define HAVE_HWLOC 1

   with

   #undef HAVE_HWLOC

   Alternatively, during the GALAHAD install (13 below), when you get to

   the prompt

     Would you like to review and modify the C compiler settings (y/N)?

   answer y, and change the variable HWLOC to read

     HWLOC='un'

   Currently this is done automatically for ifort/icc and

   gfortran/gcc to avoid compiler bugs

12. For Windows systems that use MSYS/MINGW, you will also need to set the

   environment variable MSYS2 to point to the folder that contains the

   Unix-style shell and commands, and MINGW64 to the folder that holds

   ths commands relating to the GCC/Gfortran compilers. For example,

    export MSYS2="/usr"

    export MINGW64="/c/msys64/mingw64"

    ============

    INSTALLATION

    ============

13. To install GALAHAD for a particular machine/os/compiler

   combination, move into the $GALAHAD directory,

   issue the command

     $ARCHDEFS/install_optrove

   and answer the questions as prompted. This command sets up

   machine/os/compiler-specific files, and (optionally) compiles all

   (or suitable sub-components) of GALAHAD (and SiFDec/CUTEst if required),

   plus hooks into C and Python, and to Matlab.

   You may issue the $ARCHDEFS/install_optrove command for as many

   machine/os/compiler combinations as you wish to support, and you

   will have access to each independently of the others.

   On completion of the installation, please read the message that

   gives full details of environment variables that need to be set.

14. To recompile the whole of GALAHAD, move into the directory

     $GALAHAD/src

   and issue the command

     make -f $GALAHAD/makefiles/#

   where # is a string of the form

      machine.os.compiler

   created during one of the installations described in 13 above.

   If you want the single-precision version, the appropriate command is

     make -f $GALAHAD/makefiles/# PRECIS=single

15. To recompile LANCELOT B, move into the directory

     $GALAHAD/src/

    and issue the command

     make -f $GALAHAD/makefiles/# lancelotb

    where # is as in 13 above. To recompile all the QP routines, or the

    individual packages (say) QPA, QPB or PRESOLVE, the required commands are

     make -f $GALAHAD/makefiles/# qp

     make -f $GALAHAD/makefiles/# qpa

     make -f $GALAHAD/makefiles/# qpb

     make -f $GALAHAD/makefiles/# pre

    To recompile the FILTRANE package and its dependencies, the required

    command is

     make -f $GALAHAD/makefiles/# filtrane

16. Both the makefiles and the run scripts use default values for a

    variety of variables. If you wish to use non-default values, you

    should edit the appropriate files

     $GALAHAD/makefiles/#

    and

     $GALAHAD/bin/sys/#

    Consult the file  $GALAHAD/doc/README.non-defaults for some suggestions

    =========

    EXECUTION

    =========

17. To run the QP codes qpa/qpb/qpc on the CUTEst example EXAMPLE.SIF

   issue the command

     sdgal # qpa [other options] EXAMPLE[.SIF]

   or

     sdgal # qpa [other options] EXAMPLE[.SIF]

   or

     sdgal # qpc [other options] EXAMPLE[.SIF]

   where # is as in 14 above, from the directory containing the SIF file.

   To rerun the most recently decoded example, issue the command

     gal # qpa -n [other options]

   or

     gal # qpb -n [other options]

   See README.SIF for more details.

18. To run/rerun LANCELOT B on the CUTE example EXAMPLE.SIF

   issue the command

     sdgal # lancelot [other options] EXAMPLE[.SIF]

   where # is as in 14 above, from the directory containing the SIF file.

   To rerun the most recently decoded example, issue the command

     gal # lancelot [other options]

   See README.SIF for more details.

19. To run/rerun FILTRANE on the CUTE example EXAMPLE.SIF

   issue the command

     sdgal # filtrane [other options] EXAMPLE[.SIF]

   where # is as in 14 above, from the directory containing the SIF file.

   To rerun the most recently decoded example, issue the command

     gal # filtrane [other options]

   See README.SIF for more details.

    =======

    TESTING

    =======

20. To test that the installation of GALAHAD has been successful, you can

    move into the directory

      $GALAHAD/src

    and issue the command

      make -f $GALAHAD/makefiles/# tests

    where # is as 14 above - for a single precision installation, the command is

      make -f $GALAHAD/makefiles/# test PRECIS=single

    To test LANCELOT, move into $GALAHAD/src/lancelot , and issue the same

    command, to test the QP routines, do the same in the directory

    $GALAHAD/src/all_qp , and to test the regularization packages and

    the global optimization codes do the same from $GALAHAD/src/all_rq

    and $GALAHAD/src/all_go respectively.

    To test the C interfaces, again move into the directory

      $GALAHAD/src

    and issue the command

      make -f $GALAHAD/makefiles/# test_all_ciface

21. If you are not using CUTEst, the GALAHAD link library for the

    precision you compiled with is in $GALAHAD/objects/#/(precision)/

    where (precision) is double or single, and # is as above.

    You should add this to your LIBPATH environment variable,

    and may then link the library with the -lgalahad compiler flag.

    Access to optional auxiliary libraries is via

     -lgalahad_hsl  -lgalahad_spral -lgalahad_mkl_pardiso

     -lgalahad_pardiso -lgalahad_wsmp -lgalahad_pastix -lgalahad_mumps

     -lgalahad_mpi -galahad_umfpack -lgalahad_metis_dummy

     -lgalahad_lapack -lgalahad_blas

    as appropriate; any of these dummies may be replaced by their real

    equivalents by using the proper library name, but note that

    access to Metis 4 or 5 requires -lgalahad_metis4 or _metis5.

    C versions may be accessed by additionally pre-pending

      -lgalahad_c -lgalahad_hsl_c

    to the previous list

    =============

    DOCUMENTATION

    =============

22. Documentation for package "pack" is available as follows:

     - Fortran. PDF documentation is in $GALAHAD/doc/"pack".pdf

     - C. HTML documenation is available online from

          https://ralna.github.io/galahad_docs/html/C .

          There is also inferior PDF documentation in $GALAHAD/doc/"pack"_c.pdf

          and a man page in $GALAHAD/man/man3/"pack"_c.3, with a

          an introductory man page in $GALAHAD/man/man3/galahad_c.3

     - Python. HTML documenation is online as

          https://ralna.github.io/galahad_docs/html/Python .

     - Julia. HTML documenation is online as

          https://ralna.github.io/galahad_docs/html/Julia .

     - Matlab. help is provided using hslp galahad_"pack" within Matlab

     - general. An introductory paper is in $GALAHAD/doc/galahad.pdf

[23. If you like using graphical user-interfaces, why not try the GALAHAD

     python GUI(see $GAHALAD/doc/README.gui for details). This has not

     been updated in years, so is probably of limited use.]

    ====

    NEWS

    ====

24. Refer to the GALAHAD WWW page

      http://galahad.rl.ac.uk/galahad-www/

    for updates/bug fixes/news.

    ================

    REPORTING ISSUES

    ================

25. If you have issues that you would like to report, such as potential bugs

    or extensons that might be useful, please use the issues page

       https://github.com/ralna/GALAHAD/issues

    and we will respond as quickly as we can.

Best of luck

 Nick Gould

 Dominique Orban

 Philippe Toint

For GALAHAD productions

25 April 2002

From version 4.2, additionally with

 Jari Fowkes

 Alexis Montoison

This version, 5.1

5th January 2025