From 04120b9fdd933f11db2977ab7552cb920583cc38 Mon Sep 17 00:00:00 2001 From: easifem Date: Thu, 8 Dec 2022 00:44:50 +0900 Subject: [PATCH 1/2] Improve README. --- CHANGES | 3 + README.md | 453 +++++++++++++++++++++++++++++++++++------------------- 2 files changed, 300 insertions(+), 156 deletions(-) diff --git a/CHANGES b/CHANGES index f51e34bd8..a2f2b24ab 100644 --- a/CHANGES +++ b/CHANGES @@ -1,5 +1,8 @@ arpack-ng - 3.9.0 +[ Vikas Sharma ] + * Improve README. + [ Fabien PΓ©an ] * CI: Enable job `windows_latest_cmake` to run all tests * CMake: Fix BLAS and LAPACK static library order needed to consume the library on Windows with static linkage diff --git a/README.md b/README.md index 1dc92b230..cab992726 100644 --- a/README.md +++ b/README.md @@ -1,185 +1,326 @@ -ARPACK-NG is a collection of Fortran77 subroutines designed to solve large scale -eigenvalue problems. - -
-[![Coverage Status](https://coveralls.io/repos/github/opencollab/arpack-ng/badge.svg?branch=master)](https://coveralls.io/github/opencollab/arpack-ng?branch=master) - -Important Features: - -* Reverse Communication Interface. -* Single and Double Precision Real Arithmetic Versions for Symmetric, - Non-symmetric, Standard or Generalized Problems. -* Single and Double Precision Complex Arithmetic Versions for Standard or - Generalized Problems. -* Routines for Banded Matrices - Standard or Generalized Problems. -* Routines for The Singular Value Decomposition. -* Example driver routines that may be used as templates to implement numerous - Shift-Invert strategies for all problem types, data types and precision. -* arpackmm: utility to test arpack with matrix market files. - Note: to run this utility, you need the eigen library (to handle RCI). -* ILP64 support: - * Sequential arpack supports ILP64, but, parallel arpack doesn't. - * reminder: you can NOT mix ILP64 with LP64. If you compile arpack-ng with ILP64 - (resp. LP64) support, you MUST insure your BLAS/LAPACK is compliant with ILP64 - (resp. LP64). - * users: set INTERFACE64 at configure time. - * F77/F90 developers: - * all files which needs ILP64 support must include "arpackicb.h". - * when coding, use i_int (defined in arpackicb.h) instead of c_int. - i_int stands for "iso_c_binding int": it's #defined to c_int or c_int64_t - according to the architecture. - * C/C++ developers: - * all files which needs ILP64 support must include "arpackdef.h". - * when coding, use a_int (defined in arpackdef.h) instead of int. - a_int stands for "architecture int": it's #defined to int or int64_t according - to the architecture. - * example: to test arpack with sequential ILP64 MKL assuming you use gnu compilers - ```$ ./bootstrap - $ export FFLAGS='-DMKL_ILP64 -I/usr/include/mkl' - $ export FCFLAGS='-DMKL_ILP64 -I/usr/include/mkl' - $ export LIBS='-Wl,--no-as-needed -L/usr/lib/x86_64-linux-gnu -lmkl_sequential -lmkl_core -lpthread -lm -ldl' - $ export INTERFACE64=1 - $ ./configure --with-blas=mkl_gf_ilp64 --with-lapack=mkl_gf_ilp64 - $ make all check``` -* pyarpack: python support based on Boost.Python.Numpy exposing C++ API. - Check out ./EXAMPLES/PYARPACK/README for more details. - -This project started as a joint project between Debian, Octave and Scilab in order to -provide a common and maintained version of arpack. +# arpack-ng [![arpack-ng CI/CD](https://github.com/opencollab/arpack-ng/actions/workflows/jobs.yml/badge.svg)](https://github.com/opencollab/arpack-ng/actions/workflows/jobs.yml) + +ARPACK-NG is a collection of Fortran77 subroutines designed to solve large scale eigenvalue problems. +| mandatory dependencies | optional dependencies | category | +|------------------------|---------------------------|---------------| +| BLAS, LAPACK | MPI, Eigen3, Boost.Python | LinearAlgebra | + +## About the project + +This project started as a joint project between Debian, Octave and Scilab in order to provide a common and maintained version of arpack. This is now a community project maintained by a few volunteers. +Indeed, no single release has been published by Rice university for the last few years and since many software (Octave, Scilab, R, Matlab...) +forked it and implemented their own modifications, arpack-ng aims to tackle this by providing a common repository, maintained versions with a testsuite. +`arpack-ng` is replacing arpack almost everywhere. + +## Important Features + +- Reverse Communication Interface (RCI). +- Single and Double Precision Real Arithmetic Versions for Symmetric, Non-symmetric, Standard or Generalized Problems. +- Single and Double Precision Complex Arithmetic Versions for Standard or Generalized Problems. +- Routines for Banded Matrices - Standard or Generalized Problems. +- Routines for The Singular Value Decomposition. +- Example driver routines that may be used as templates to implement numerous +- Shift-Invert strategies for all problem types, data types and precision. +- `arpackmm`: utility to test arpack with matrix market files. Note: to run this utility, you need the eigen library (to handle RCI). + +## Documentation + +Within DOCUMENTS directory there are three files for templates on how to invoke the computational modes of ARPACK. + +- ex-sym.doc +- ex-nonsym.doc and +- ex-complex.doc + +Also look in the README.MD file for explanations concerning the +other documents. + +## ILP64 support + +About ILP64 support: + +- Sequential arpack supports [ILP64](https://www.intel.com/content/www/us/en/develop/documentation/onemkl-linux-developer-guide/top/linking-your-application-with-onemkl/linking-in-detail/linking-with-interface-libraries/using-the-ilp64-interface-vs-lp64-interface.html), but, parallel arpack doesn't. +- Reminder: you can NOT mix `ILP64` with `LP64`. If you compile `arpack-ng` with `ILP64` (resp. `LP64`) support, you MUST insure your BLAS/LAPACK is compliant with `ILP64` (resp. `LP64`). +- Set `INTERFACE64` at configure time. + +Note for F77/F90 developers: + +- All files which needs `ILP64` support must include `"arpackicb.h"`. +- When coding, use `i_int` (defined in `arpackicb.h`) instead of `c_int`. `i_int` stands for `iso_c_binding int`: it's `#defined` to `c_int` or `c_int64_t` according to the architecture. + +Note for C/C++ developers: + +- All files which needs `ILP64` support must include `"arpackdef.h"`. +- When coding, use `a_int` (defined in `arpackdef.h`) instead of `int`. Here, `a_int` stands for "architecture int": it's `#defined` to `int` or `int64_t` according to the architecture. + +**Example**: to test arpack with sequential `ILP64` MKL assuming you use gnu compilers + +```bash +$ ./bootstrap +$ export FFLAGS='-DMKL_ILP64 -I/usr/include/mkl' +$ export FCFLAGS='-DMKL_ILP64 -I/usr/include/mkl' +$ export LIBS='-Wl,--no-as-needed -L/usr/lib/x86_64-linux-gnu -lmkl_sequential -lmkl_core -lpthread -lm -ldl' +$ export INTERFACE64=1 +$ ./configure --with-blas=mkl_gf_ilp64 --with-lapack=mkl_gf_ilp64 +$ make all check +``` + +## ISO_C_BINDING support + +About ISO_C_BINDING support: + +- The install will now provide `arpack.h/hpp`, `parpack.h/hpp` and friends. +- Examples of use can be found in `./TESTS` and` ./PARPACK/TESTS/MPI`. + +Those who are interested in `ISO_C_BINDING` support can checkout following links for more informations. + +- +- +- + +**Example**: to test arpack with ISO_C_BINDING + +```bash +$ ./configure --enable-icb +$ cmake -D ICB=ON +``` + +## Eigen support + +`arpack-ng` provides C++ eigensolver based on `eigen`. + +Check out `./EXAMPLES/MATRIX_MARKET/README` for more details. + +**Example**: to test arpack with `eigen` + +```bash +$ mkdir build +$ cd build +$ cmake -D EXAMPLES=ON -D ICB=ON -D ICBEXMM=ON .. +$ make all check +``` + +## Python support + +`pyarpack`: python support based on `Boost.Python.Numpy` exposing C++ API. +`pyarpack` exposes in python the `arpack-ng` C++ eigensolver (based on `eigen`). + +Check out `./EXAMPLES/PYARPACK/README` for more details. + +**Example**: to test arpack with python3 + +```bash +$ mkdir build +$ cd build +$ cmake -D EXAMPLES=ON -D ICB=ON -D ICBEXMM=ON -D PYTHON3=ON .. +$ make all check +``` + +## πŸ“ Directory structure + +- You have successfully unbundled ARPACK-NG` and are now in the ARPACK-NG directory that was created for you. + +- The directory SRC contains the top level routines including the highest level **reverse communication interface** routines + + - `ssaupd`, `dsaupd`: symmetric single and double precision + - `snaupd`, `dnaupd`: non-symmetric single and double precision + - `cnaupd`, `znaupd`: complex non-symmetric single and double precision + - The headers of these routines contain full documentation of calling sequence and usage. + - Additional information is given in the `/DOCUMENTS` directory. -Indeed, no single release has been published by Rice university for the last -few years and since many software (Octave, Scilab, R, Matlab...) forked it and -implemented their own modifications, arpack-ng aims to tackle this by providing -a common repository, maintained versions with a testsuite. +- The directory `PARPACK` contains the Parallel ARPACK routines. -arpack-ng is replacing arpack almost everywhere. +- Example driver programs that illustrate all the computational modes, data types and precisions may be found in the EXAMPLES directory. Upon executing the `ls EXAMPLES` command you should see the following directories -1. You have successfully unbundled ARPACK-NG and are now in the ARPACK-NG - directory that was created for you. + ```bash + β”œβ”€β”€ BAND + β”œβ”€β”€ COMPLEX + β”œβ”€β”€ Makefile.am + β”œβ”€β”€ MATRIX_MARKET + β”œβ”€β”€ NONSYM + β”œβ”€β”€ PYARPACK + β”œβ”€β”€ README + β”œβ”€β”€ SIMPLE + β”œβ”€β”€ SVD + └── SYM + ``` -2. The directory SRC contains the top level routines including - the highest level reverse communication interface routines + - Example programs for banded, complex, nonsymmetric, symmetric, and singular value decomposition may be found in the directories BAND, COMPLEX, NONSYM, SYM, SVD respectively. + - Look at the README file for further information. + - To get started, get into the SIMPLE directory to see example programs that illustrate the use of ARPACK in the simplest modes of operation for the most commonly posed standard eigenvalue problems. -* ssaupd, dsaupd - symmetric single and double precision -* snaupd, dnaupd - non-symmetric single and double precision -* cnaupd, znaupd - complex non-symmetric single and double precision +> Example programs for Parallel ARPACK may be found in the directory `PARPACK/EXAMPLES`. Look at the README file for further information. - The headers of these routines contain full documentation of calling - sequence and usage. Additional information is in the DOCUMENTS directory. +## Install πŸš€ - The directory PARPACK contains the Parallel ARPACK routines. +### Getting arpack-ng +Unlike ARPACK, ARPACK-NG is providing autotools and cmake based build system. In addition, `ARPACK-NG` also provides +`iso_c_binding` support, which enables to call fortran subroutines natively from C or C++. -3. Example driver programs that illustrate all the computational modes, - data types and precisions may be found in the EXAMPLES directory. - Upon executing the 'ls EXAMPLES' command you should see +First, obtain the source code πŸ“₯ from github: -* BAND -* COMPLEX -* NONSYM -* README -* SIMPLE -* SVD -* SYM +```bash +$ git clone https://github.com/opencollab/arpack-ng.git +$ cd ./arpack-ng +``` - Example programs for banded, complex, nonsymmetric, symmetric, - and singular value decomposition may be found in the directories - BAND, COMPLEX, NONSYM, SYM, SVD respectively. Look at the README - file for further information. To get started, get into the SIMPLE - directory to see example programs that illustrate the use of ARPACK in - the simplest modes of operation for the most commonly posed - standard eigenvalue problems. +If you prefer the ssh to obtain the source code, then use: +```bash +$ git clone git@github.com:opencollab/arpack-ng.git +$ cd ./arpack-ng +``` - Example programs for Parallel ARPACK may be found in the directory - PARPACK/EXAMPLES. Look at the README file for further information. +> Note, It is recommended to install `arpack` at standard location on your system by using your root privilege. - The following instructions explain how to make the ARPACK library. +### Using autotools -4. Unlike ARPACK, ARPACK-NG is providing autotools and cmake based build - system and iso_c_binding support (which enables to call fortran - subroutines natively from C or C++). +In the source directory, use the following commands to configure, build and install `arpack-ng`. -Therefore, the classical commands should work as expected: - - - $ sh bootstrap - $ ./configure - $ make - $ make check - $ make install +```bash +$ sh bootstrap +$ ./configure --enable-mpi +$ make +$ make check +$ sudo make install +``` -Furthermore, ARPACK-NG now provides CMake functionality: - - $ mkdir build - $ cd build - $ cmake -D EXAMPLES=ON -D MPI=ON -D BUILD_SHARED_LIBS=ON .. - $ make - $ make install - builds everything including examples and parallel support (with MPI). +Congratulations πŸŽ‰, you have installed `arpack` lib using autotools (caution: you need `sudo` to install in your system). -To use arpack from CMake, use ARPACK::ARPACK target: +The above-mentioned process will build everything including the examples and parallel support using MPI. - find_package(arpack-ng) - add_executable(main main.f) - target_include_directories(main PUBLIC ARPACK::ARPACK) - target_link_libraries(main ARPACK::ARPACK) +### Using cmake -To use parpack from CMake, use PARPACK::PARPACK target: +You can install `ARPACK-NG` by using cmake. If you do not have cmake, then please download the binary from `pip` using: - find_package(arpack-ng) - add_executable(main main.f) - target_include_directories(main PUBLIC PARPACK::PARPACK) - target_link_libraries(main PARPACK::PARPACK) +```bash +$ python3 -m pip install cmake +$ which cmake && cmake --version +``` + +After installing cmake, follow the instruction given below. + +Caution: Make sure you are in source directory of ARPACK-NG. + +```bash +$ mkdir build +$ cd build +$ cmake -D EXAMPLES=ON -D MPI=ON -D BUILD_SHARED_LIBS=ON .. +$ make +$ sudo make install +``` + +✨ Congratulations, you have installed `arpack` lib using cmake (caution: you need `sudo` to install in your system). + +The above-mentioned process will build everything including the examples and parallel support using MPI. + +### Customize build / install + +You can also customize the installation of `arpack` using the autotools. + +To customize the install directories: + +```bash +$ LIBSUFFIX="64" ./configure +$ make all install +``` + +To enable ILP64 support: + +```bash +$ INTERFACE64="1" ITF64SUFFIX="ILP64" ./configure +$ make all install +``` + +To enable ISO_C_BINDING support: + +```bash +$ ./configure --enable-icb +``` + +You can customize the build by declaring the cmake options during configuration. + +To customize the install directories: + +```bash +$ cmake -D LIBSUFFIX="64" .. +$ make all install +``` + +To enable ILP64 support: + +```bash +$ cmake -D INTERFACE64=ON -D ITF64SUFFIX="ILP64" .. +$ make all install +``` + +To enable ISO_C_BINDING support: + +```bash +$ cmake -D ICB=ON +``` + +## Supported Operating Systems: + +### Linux support + +`arpack-ng` runs on debian-based distros. + +### Mac OS support On mac OS, with GNU compilers, you may need to customize options: - $ LIBS="-framework Accelerate" FFLAGS="-ff2c -fno-second-underscore" FCFLAGS="-ff2c -fno-second-underscore" ./configure - -To build with code coverage: - - $ mkdir build - $ cd build - $ cmake -DCOVERALLS=ON -DCMAKE_BUILD_TYPE=Debug .. - $ make all check test coveralls - -To get iso_c_binding support: - - $ ./configure --enable-icb - $ cmake -D ICB=ON - The install will now provide arpack.h/hpp, parpack.h/hpp and friends. - Examples of use can be found in ./TESTS and ./PARPACK/TESTS/MPI. - A few related links can be found here: - - * http://fortranwiki.org/fortran/show/ISO_C_BINDING - * http://fortranwiki.org/fortran/show/Generating+C+Interfaces - * https://www.roguewave.com/sites/rw/files/attachments/StandardizedMixedLanguageProgrammingforCandFortran.pdf - -5. Within DOCUMENTS directory there are three files - -* ex-sym.doc -* ex-nonsym.doc and -* ex-complex.doc - - for templates on how to invoke the computational modes of ARPACK. - Also look in the README.MD file for explanations concerning the - other documents. - -Custom installation examples: - - $ LIBSUFFIX="64" ./configure; make all install - $ cmake -DLIBSUFFIX="64" ..; make all install - - $ INTERFACE64="1" ITF64SUFFIX="ILP64" ./configure; make all install - $ cmake -DINTERFACE64=ON -DITF64SUFFIX="ILP64" ..; make all install - - $ LIBSUFFIX="64" INTERFACE64="1" ITF64SUFFIX="ILP64" ./configure; make all install - $ cmake -DLIBSUFFIX="64" -DINTERFACE64=ON -DITF64SUFFIX="ILP64" ..; make all install +```bash +$ LIBS="-framework Accelerate" FFLAGS="-ff2c -fno-second-underscore" FCFLAGS="-ff2c -fno-second-underscore" ./configure +``` + +### Windows support + +`arpack-ng` runs on windows using `mingw64`. + +## Using arpack-ng from your own codebase + +### With autotools + +First, set `PKG_CONFIG_PATH` to the location in the installation directory where `arpack.pc` lies. + +Then, insert the following lines in your `configure.ac`: +``` +PKG_CHECK_MODULES([ARPACK], [arpack]) +AC_SUBST([ARPACK_CFLAGS]) +AC_SUBST([ARPACK_LIBS]) +``` + +Note: make sure you have installed `pkg-config`. + +### With CMake + +You can use arpack in your CMake builds by using `ARPACK::ARPACK` target. For example, + +```cmake +FIND_PACKAGE(arpack-ng) +ADD_EXECUTABLE(main main.f) +TARGET_INCLUDE_DIRECTORIES(main PUBLIC ARPACK::ARPACK) +TARGET_LINK_LIBRARIES(main ARPACK::ARPACK) +``` + +To use PARPACK in your Cmake builds, use `PARPACK::PARPACK` target: + +```cmake +FIND_PACKAGE(arpack-ng) +ADD_EXECUTABLE(main main.f) +TARGET_INCLUDE_DIRECTORIES(main PUBLIC PARPACK::PARPACK) +TARGET_LINK_LIBRARIES(main PARPACK::PARPACK) +``` + +Note: Make sure to update `CMAKE_MODULE_PATH` env variable (otheriwse, `find_package` won't find arpack-ng cmake file). + +## Using MKL instead of BLAS / LAPACK How to use arpack-ng with Intel MKL: -* Let autotools/cmake find MKL for you based on pkg-config files (setting `PKG_CONFIG_PATH`) or cmake options (`BLA_VENDOR=Intel`). -* Refers to the Intel Link Advisor: https://www.intel.com/content/www/us/en/developer/tools/oneapi/onemkl-link-line-advisor.html. +- Let autotools/cmake find MKL for you based on pkg-config files (setting `PKG_CONFIG_PATH`) or cmake options (`BLA_VENDOR=Intel`). +- Refers to the Intel Link Advisor: . - Good luck and enjoy. +## Good luck and enjoy 🎊 From c29729af6d29ac6b0eb8bb8d7539a65a3c969193 Mon Sep 17 00:00:00 2001 From: Franck HOUSSEN Date: Sat, 11 Feb 2023 13:53:09 +0100 Subject: [PATCH 2/2] New upstream release. --- CHANGES | 52 ++++++++++++++++++++++++++-------------------------- 1 file changed, 26 insertions(+), 26 deletions(-) diff --git a/CHANGES b/CHANGES index a2f2b24ab..ee0ac71fa 100644 --- a/CHANGES +++ b/CHANGES @@ -1,45 +1,47 @@ + -- Franck Houssen Sat, 11 Feb 2023 13:52:57 +0100 + arpack-ng - 3.9.0 [ Vikas Sharma ] * Improve README. [ Fabien PΓ©an ] -* CI: Enable job `windows_latest_cmake` to run all tests -* CMake: Fix BLAS and LAPACK static library order needed to consume the library on Windows with static linkage -* Fix using ARPACK on Windows with MSVC compiler from C++17 onwards + * CI: Enable job `windows_latest_cmake` to run all tests + * CMake: Fix BLAS and LAPACK static library order needed to consume the library on Windows with static linkage + * Fix using ARPACK on Windows with MSVC compiler from C++17 onwards [ Zhentao Wang ] -* [BUG FIX] parpack.h and parpack.hpp: type of rwork should be real instead of complex. -* Allow ritz_option {"LR", "SR", "LI", "SI"} for complex eigenvalue problems in ICB. + * [BUG FIX] parpack.h and parpack.hpp: type of rwork should be real instead of complex. + * Allow ritz_option {"LR", "SR", "LI", "SI"} for complex eigenvalue problems in ICB. [ Jose E. Roman ] -* Avoid using isnan() in tests, since is GNU-specific + * Avoid using isnan() in tests, since is GNU-specific [ Tom Payerle ] -* Change the continuation line format for stat.h, debug.h + * Change the continuation line format for stat.h, debug.h [ John Doe ] -* Avoid calling [c|z]dotc for better portability on macOS + * Avoid calling [c|z]dotc for better portability on macOS [ Dima Pasechnik ] -* [BUG FIX] autotools: replace obsolete AC_TRY_COMPILE macros. -* Support for NAG's nagfor Fortran compiler + * [BUG FIX] autotools: replace obsolete AC_TRY_COMPILE macros. + * Support for NAG's nagfor Fortran compiler [ Franck Houssen ] -* Create one .cmake file per arpack-ng flavor (32-bits, 64-bits, ILP64). -* Test autotools pkg-config (*.pc files) with/without LIBSUFFIX/ITF64SUFFIX. -* Test CMake find_package (*.cmake files) with/without LIBSUFFIX/ITF64SUFFIX. -* [BUG FIX] autotools: ICB must be checked first (MPI changes compilers). -* [BUG FIX] BLAS/LAPACK: allow suffixes in case BLAS/LAPACK can not provide ICB. -* [BUG FIX] Compile C programs with ICB. -* arpackmm: command line bug fix. -* arpackmm: restart bug fix. -* pyarpack: fix compilation warning, test on macos and latest boost-python (1.79). -* arpackSolver: fix error messages. -* [BUG FIX] Make sure iseed is always initialized to values allowed by lapack ?larnv. -* [BUG FIX] According to lapack doc of ?larnv, iseed(4) must be odd. -* [BUG FIX] Use MPI ICB types (mpi_f08) instead of integer(kind=i_int). -* parpack: no ILP64 support. + * Create one .cmake file per arpack-ng flavor (32-bits, 64-bits, ILP64). + * Test autotools pkg-config (*.pc files) with/without LIBSUFFIX/ITF64SUFFIX. + * Test CMake find_package (*.cmake files) with/without LIBSUFFIX/ITF64SUFFIX. + * [BUG FIX] autotools: ICB must be checked first (MPI changes compilers). + * [BUG FIX] BLAS/LAPACK: allow suffixes in case BLAS/LAPACK can not provide ICB. + * [BUG FIX] Compile C programs with ICB. + * arpackmm: command line bug fix. + * arpackmm: restart bug fix. + * pyarpack: fix compilation warning, test on macos and latest boost-python (1.79). + * arpackSolver: fix error messages. + * [BUG FIX] Make sure iseed is always initialized to values allowed by lapack ?larnv. + * [BUG FIX] According to lapack doc of ?larnv, iseed(4) must be odd. + * [BUG FIX] Use MPI ICB types (mpi_f08) instead of integer(kind=i_int). + * parpack: no ILP64 support. [ Haoyang Liu ] * CMake: minimum required version changed to 3.0 @@ -56,8 +58,6 @@ arpack-ng - 3.9.0 [ Juan JosΓ© GarcΓ­a-Ripoll ] * Adapt the C/C++ interface to accept also MSVC's non-standard complex types. - -[ Juan JosΓ© GarcΓ­a Ripoll ] * Propagate dependencies to CMake targets that use arpack-ng: - Create CMake-generated targets and configuration files that keep track of arpack's dependencies (libraries, directories) and expose them to users.