Skip to content

Commit 19b8fcc

Browse files
brunowubrunowu
committed
update Readme
1 parent ae51f89 commit 19b8fcc

File tree

1 file changed

+75
-12
lines changed

1 file changed

+75
-12
lines changed

‎README.md

Lines changed: 75 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
<img src="docs/images/ChASE_Logo_RGB.png" alt="Matrix Generation Pattern" style="zoom:60%;" />
1+
<img src="docs/images/ChASE_Logo_RGB.png" alt="Matrix Generation Pattern" style="zoom:40%;" />
22

33
# ChASE: a Chebyshev Accelerated Subspace Eigensolver for Dense Eigenproblems
44

@@ -22,27 +22,90 @@ The library comes in two main versions:
2222

2323
1. **ChASE-MPI**
2424

25-
ChASE-MPI is the default version of the library and can be installed with the minimum amount of dependencies (BLAS, LAPACK, and MPI).
26-
27-
ChASE-MPI supports different configurations depending on the available hardware resources.
28-
29-
> - **Shared memory build:** This is the simplest configuration and should be exclusively selected when ChASE is used on only one computing node or on a single CPU. The simplicity of this configuration resides in the way the Matrix-Matrix kernel is implemented with respect to the full MPI build.
30-
> - **MPI+Threads build:** On multi-core homogeneous CPU clusters ChASE is best used in its pure MPI build. In this configuration, ChASE is typically used with one MPI rank per computing node and as many threads as number of available cores per node.
31-
> - **GPU build:** ChASE-MPI can be configured to take advantage of graphics card on heterogeneous computing clusters. Currently we support the use of one or more GPU cards per computing node in a number of flexible configurations: for instance on computing nodes with 4 cards per node one can choose to compile and execute the program with one, two or four GPU card per MPI rank.
25+
ChASE-MPI is the default version of the library and can be installed with the minimum amount of dependencies (BLAS, LAPACK, and MPI). It supports different configurations depending on the available hardware resources.
3226

27+
- **Shared memory build:** This is the simplest configuration and should be exclusively selected when ChASE is used on only one computing node or on a single CPU.
28+
- **MPI+Threads build:** On multi-core homogeneous CPU clusters, ChASE is best used in its pure MPI build. In this configuration, ChASE is typically used with one MPI rank per NUMA domain and as many threads as number of available cores per NUMA domain.
29+
- **GPU build:** ChASE-MPI can be configured to take advantage of GPUs on heterogeneous computing clusters. Currently we support the use of one or more GPU cards per computing node in a number of flexible configurations: for instance on computing nodes with 4 cards per node one can choose to compile and execute the program with one, two or four GPU card per MPI rank.
30+
3331
ChASE support two types of data distribution of matrix `A` across 2D MPI grid:
3432

35-
> - **Block Distribution**: each MPI rank of 2D grid is assigned a block of dense matrix **A**.
36-
> - **Block-Cyclic Distribution**: This distribution scheme was introduced for the implementation of dense matrix computations on distributed-memory machines, to improve the load balance of matrix computation if the amount of work differs for different entries of a matrix. For more details about **Block-Cyclic Distribution**, please refer to [Netlib](https://www.netlib.org/scalapack/slug/node75.html) website.
33+
- **Block Distribution**: each MPI rank of 2D grid is assigned a block of dense matrix **A**.
34+
35+
- **Block-Cyclic Distribution**: an distribution scheme for implementation of dense matrix computations on distributed-memory machines, to improve the load balance of matrix computation if the amount of work differs for different entries of a matrix. For more details, please refer to [Netlib](https://www.netlib.org/scalapack/slug/node75.html) .
3736

3837
2. **ChASE-Elemental**
3938

4039
ChASE-Elemental requires the additional installation of the [Elemental](https://github.com/elemental/Elemental) library.
4140

41+
## Quick Start
42+
43+
### Installing Dependencies
44+
45+
```bash
46+
#Linux Operating System
47+
sudo apt-get install cmake #install CMake
48+
sudo apt-get install build-essential #install GNU Compiler
49+
sudo apt-get install libopenblas-dev #install BLAS and LAPACK
50+
sudo apt-get install libopenmpi-dev #install MPI
51+
52+
#Apple Mac Operating System
53+
sudo port install cmake #install CMake
54+
sudo port install gcc10 #install GNU Compiler
55+
sudo port select --set gcc mp-gcc10 #Set installed GCC as C compiler
56+
sudo port install OpenBLAS +native #install BLAS and LAPACK
57+
sudo port install openmpi #install MPI
58+
sudo port select --set mpi openmpi-mp-fortran #Set installed MPI as MPI compiler
59+
```
60+
61+
### Cloning ChASE source code
62+
63+
```bash
64+
git clone https://github.com/ChASE-library/ChASE #cloning the ChASE repository
65+
git checkout v1.0.0 #it is recommended to check out the latest stable tag.
66+
```
67+
68+
### Building and Installing the ChASE library
69+
70+
```bash
71+
cd ChASE/
72+
mkdir build
73+
cd build/
74+
cmake .. -DCMAKE_INSTALL_PREFIX=${ChASEROOT}
75+
make install
76+
```
77+
78+
More details about the installation on both local machine and clusters, please refer to [User Documentation](https://chase-library.github.io/ChASE/quick-start.html).
79+
4280
## Documentation
4381
4482
The documentation of ChASE is available [online](https://chase-library.github.io/ChASE/index.html).
4583
84+
Compiling the documentation in local requires enable `-DBUILD_WITH_DOCS=ON` flag when compiling ChASE library:
85+
86+
```bash
87+
cmake .. -DBUILD_WITH_DOCS=ON
88+
```
89+
90+
## Examples
91+
92+
Multiple examples are provided, which helps user get familiar with ChASE.
93+
94+
**Build ChASE with Examples** requires enable `-DBUILD_WITH_EXAMPLES=ON` flag when compiling ChASE library:
95+
96+
```bash
97+
cmake .. -DBUILD_WITH_EXAMPLES=ON
98+
```
99+
100+
**5 examples are available** in folder [examples](https://github.com/ChASE-library/ChASE/tree/master/examples):
101+
102+
0. The example [0_hello_world](https://github.com/ChASE-library/ChASE/tree/master/examples/0_hello_world) constructs a simple Clement matrix and find a given number of its eigenpairs.
103+
104+
1. The example [1_sequence_eigenproblems](https://github.com/ChASE-library/ChASE/tree/master/examples/1_sequence_eigenproblems) illustrates how ChASE can be used to solve a sequence of eigenproblems.
105+
2. The example [2_input_output](https://github.com/ChASE-library/ChASE/tree/master/examples/2_input_output) provides the configuration of parameters of ChASE from command line (supported by Boost); the parallel I/O which loads the local matrices into the computing nodes in parallel.
106+
3. The example [3_installation](https://github.com/ChASE-library/ChASE/tree/master/examples/3_installation) shows the way to link ChASE to other applications.
107+
4. The example [4_gev](https://github.com/ChASE-library/ChASE/tree/master/examples/4_gev) shows an example to solve Generalized Eigenproblem via the Cholesky Factorization provided by ScaLAPACK.
108+
46109
## Developers
47110
48111
### Main developers
@@ -75,8 +138,8 @@ This repository mirrors the principal Gitlab repository. If you want to contribu
75138
76139
The main reference of ChASE is [1] while [2] provides some early results on scalability and usage on sequences of eigenproblems generated by Materials Science applications.
77140
78-
> - [1] J. Winkelmann, P. Springer, and E. Di Napoli. *ChASE: a Chebyshev Accelerated Subspace iteration Eigensolver for sequences of Hermitian eigenvalue problems.* ACM Transaction on Mathematical Software, **45** Num.2, Art.21, (2019). [DOI:10.1145/3313828](https://doi.org/10.1145/3313828) , [[arXiv:1805.10121](https://arxiv.org/abs/1805.10121/) ]
79-
> - [2] M. Berljafa, D. Wortmann, and E. Di Napoli. *An Optimized and Scalable Eigensolver for Sequences of Eigenvalue Problems.* Concurrency & Computation: Practice and Experience **27** (2015), pp. 905-922. [DOI:10.1002/cpe.3394](https://onlinelibrary.wiley.com/doi/pdf/10.1002/cpe.3394) , [[arXiv:1404.4161](https://arxiv.org/abs/1404.4161) ].
141+
- [1] J. Winkelmann, P. Springer, and E. Di Napoli. *ChASE: a Chebyshev Accelerated Subspace iteration Eigensolver for sequences of Hermitian eigenvalue problems.* ACM Transaction on Mathematical Software, **45** Num.2, Art.21, (2019). [DOI:10.1145/3313828](https://doi.org/10.1145/3313828) , [[arXiv:1805.10121](https://arxiv.org/abs/1805.10121/) ]
142+
- [2] M. Berljafa, D. Wortmann, and E. Di Napoli. *An Optimized and Scalable Eigensolver for Sequences of Eigenvalue Problems.* Concurrency & Computation: Practice and Experience **27** (2015), pp. 905-922. [DOI:10.1002/cpe.3394](https://onlinelibrary.wiley.com/doi/pdf/10.1002/cpe.3394) , [[arXiv:1404.4161](https://arxiv.org/abs/1404.4161) ].
80143
81144
## Copyright and License
82145

0 commit comments

Comments
 (0)