Skip to content

Commit

Permalink
Update README.md (#708)
Browse files Browse the repository at this point in the history 
* Update README.md

* Update README.md

* removed outdated GPU instructions
  • Loading branch information
@cnpetra
cnpetra authored Feb 12, 2025
1 parent 36d9814 commit 4d0d953
Showing 1 changed file with 5 additions and 69 deletions.
74 changes: 5 additions & 69 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -30,7 +30,6 @@ author = {Cosmin G. Petra},
and when using the the PriDec solver please cite:
```
@article{wang2023,
archivePrefix = {arXiv},
author = {J. Wang and C. G. Petra},
title = {A Sequential Quadratic Programming Algorithm for Nonsmooth Problems with Upper-$\mathcal{C}^2$ Objective},
journal = {SIAM Journal on Optimization},
Expand Down Expand Up @@ -100,53 +99,7 @@ A complete list of dependencies is maintained [here](https://github.com/spack/sp
For a minimal build, HiOp requires LAPACK and BLAS. These dependencies are automatically detected by the build system. MPI is optional and by default enabled. To disable use cmake option '-DHIOP_USE_MPI=OFF'.
HiOp has support for NVIDIA **GPU-based computations** via CUDA and Magma. To enable the use of GPUs, use cmake with '-DHIOP_USE_GPU=ON'. The build system will automatically search for CUDA Toolkit. For non-standard CUDA Toolkit installations, use '-DHIOP_CUDA_LIB_DIR=/path' and '-DHIOP_CUDA_INCLUDE_DIR=/path'. For "very" non-standard CUDA Toolkit installations, one can specify the directory of cuBlas libraries as well with '-DHIOP_CUBLAS_LIB_DIR=/path'.
### Using RAJA and Umpire portability libraries
Portability libraries allow running HiOp's linear algebra either on host (CPU) or a device (GPU). RAJA and Umpire are disabled by default. You can turn them on together by passing `-DHIOP_USE_RAJA=ON` to CMake. If the two libraries are not automatically found, specify their installation directories like this:
```shell
$> cmake -DHIOP_USE_RAJA=ON -DRAJA_DIR=/path/to/raja/dir -Dumpire_DIR=/path/to/umpire/dir
```
If the GPU support is enabled, RAJA will run all HiOp linear algebra kernels on GPU, otherwise RAJA will run the kernels on CPU using an OpenMP execution policy.

### Support for GPU computations

When GPU support is on, HiOp requires Magma linear solver library and CUDA Toolkit. Both are detected automatically in most cases. The typical cmake command to enable GPU support in HiOp is
```shell
$> cmake -DHIOP_USE_GPU=ON ..
```

When Magma is not detected, one can specify its location by passing `-DHIOP_MAGMA_DIR=/path/to/magma/dir` to cmake.

For custom CUDA Toolkit installations, the locations to the (missing/not found) CUDA libraries can be specified to cmake via `-DNAME=/path/cuda/directory/lib`, where `NAME` can be any of
```
CUDA_cublas_LIBRARY
CUDA_CUDART_LIBRARY
CUDA_cudadevrt_LIBRARY
CUDA_cusparse_LIBRARY
CUDA_cublasLt_LIBRARY
CUDA_nvblas_LIBRARY
CUDA_culibos_LIBRARY
```
Below is an example for specifiying `cuBlas`, `cuBlasLt`, and `nvblas` libraries, which were `NOT_FOUND` because of a non-standard CUDA Toolkit instalation:
```shell
$> cmake -DHIOP_USE_GPU=ON -DCUDA_cublas_LIBRARY=/usr/local/cuda-10.2/targets/x86_64-linux/lib/lib64 -DCUDA_cublasLt_LIBRARY=/export/home/petra1/work/installs/cuda10.2.89/targets/x86_64-linux/lib/ -DCUDA_nvblas_LIBRARY=/export/home/petra1/work/installs/cuda10.2.89/targets/x86_64-linux/lib/ .. && make -j && make install
```

A detailed example on how to compile HiOp straight of the box on `summit.olcf.ornl.gov` is available [here](README_summit.md).

RAJA and UMPIRE dependencies are usually detected by HiOp's cmake build system.

### Kron reduction

Kron reduction functionality of HiOp is disabled by default. One can enable it by using
```shell
$> rm -rf *; cmake -DHIOP_WITH_KRON_REDUCTION=ON -DUMFPACK_DIR=/Users/petra1/work/installs/SuiteSparse-5.7.1 -DMETIS_DIR=/Users/petra1/work/installs/metis-4.0.3 .. && make -j && make install
```
Metis is usually detected automatically and needs not be specified under normal circumstances.

UMFPACK (part of SuiteSparse) and METIS need to be provided as shown above.
Please note that HiOp has support for GPU computations, for both NVIDIA and AMD hardware, via RAJA and Umpire performance portability libraries. To quickly enable the use of GPUs, use cmake with '-DHIOP_USE_GPU=ON'.
## Install with Spack
Expand All @@ -170,27 +123,10 @@ HiOp supports three types of optimization problems, each with a separate input f
More information on the HiOp interfaces are [here](src/Interface/README.md).
## Running HiOp tests and applications
HiOp is using NVBlas library when built with CUDA support. If you don't specify
location of the `nvblas.conf` configuration file, you may get an annoying
warnings. HiOp provides default `nvblas.conf` file and installs it at the same
location as HiOp libraries. To use it, set environment variable as
```bash
$ export NVBLAS_CONFIG_FILE=<hiop install dir>/lib/nvblas.conf
```
or, if you are using C-shell, as
```shell
$ setenv NVBLAS_CONFIG_FILE <hiop install dir>/lib/nvblas.conf
```
## Issues
Users are highly encouraged to report any issues they found when using HiOp.
## Existing issues
Users are highly encouraged to report any issues they found from using HiOp.
One known issue is that there is some minor inconsistence between HiOp and linear package STRUMPACK.
When STRUMPACK is compiled with MPI (and Scalapack), user must set flag `HIOP_USE_MPI` to `ON` when compiling HiOp.
Otherwise HiOp won't load MPI module and will return an error when links to STRUMPACK, since the later one requires a valid MPI module.
Similarly, if both Magma and STRUMPACK are linked to HiOp, user must guarantee the all the packages are compiled by the same CUDA compiler.
User can check other issues and their existing status from https://github.com/LLNL/hiop
## Acknowledgments
Expand All @@ -203,10 +139,10 @@ HiOp has been developed under the financial support of:
# Contributors
HiOp is written by Cosmin G. Petra ([email protected]), Nai-Yuan Chiang ([email protected]), and Jingyi "Frank" Wang ([email protected]) from LLNL and has received important contributions from Asher Mancinelli (PNNL), Slaven Peles (ORNL), Cameron Rutherford (PNNL), Jake K. Ryan (PNNL), and Michel Schanen (ANL).
HiOp is written by Cosmin G. Petra ([email protected]), Nai-Yuan Chiang ([email protected]), Jingyi "Frank" Wang (wang125@llnl.gov), and Tucker Hartland (hartland1@llnl.gov) from LLNL and has received important contributions from Asher Mancinelli (PNNL), Slaven Peles (ORNL), Cameron Rutherford (PNNL), Jake K. Ryan (PNNL), and Michel Schanen (ANL).
# Copyright
Copyright (c) 2017-2021, Lawrence Livermore National Security, LLC. All rights reserved. Produced at the Lawrence Livermore National Laboratory. LLNL-CODE-742473. HiOp is free software; you can modify it and/or redistribute it under the terms of the BSD 3-clause license. See [COPYRIGHT](/COPYRIGHT) and [LICENSE](/LICENSE) for complete copyright and license information.
Copyright (c) 2017-2025, Lawrence Livermore National Security, LLC. All rights reserved. Produced at the Lawrence Livermore National Laboratory. LLNL-CODE-742473. HiOp is free software; you can modify it and/or redistribute it under the terms of the BSD 3-clause license. See [COPYRIGHT](/COPYRIGHT) and [LICENSE](/LICENSE) for complete copyright and license information.

0 comments on commit 4d0d953

Please sign in to comment.