|
3 | 3 | [](https://github.com/JuliaParallel/PETSc.jl/actions/workflows/ci.yml) |
4 | 4 | [](https://juliaparallel.github.io/PETSc.jl/dev/) |
5 | 5 |
|
6 | | -This package provides a low level interface for [PETSc](https://www.mcs.anl.gov/petsc/) and allows combining julia features (such as automatic differentiation) with the PETSc infrastructure and nonlinear solvers. |
| 6 | +`PETSc.jl` provides an interface to the Portable, Extensible Toolkit for Scientific Computation ([PETSc](https://petsc.org)) library, allowing the combination of Julia features (such as automatic differentiation) with the PETSc's infrastructure, including linear, nonlinear, and optimization solvers, timesteppers, domain management (DM), and more, in a distributed-memory (MPI) environment. |
7 | 7 |
|
8 | | -## Installation |
| 8 | +This package comprises two main components: |
| 9 | + |
| 10 | +1. An automatically generated, low-level interface for large parts of the PETSc API (see `PETSc.LibPETSc`). |
| 11 | +2. A curated, high-level, more Julianic interface for selected functionality. |
| 12 | + |
| 13 | +The low-level interface covers nearly the entire PETSc API, but may be awkward to work with and likely requires previous experience with PETSc to use effectively. The high level interface is designed to be more familiar and convenient for Julia users, and allows, for example, to set matrix entries with `A[1,2] = 3.0`, rather than having to call `LibPETSc.MatSetValue`. It, however, exposes only a small portion of the functionality of the underlying library. |
9 | 14 |
|
| 15 | +## Installation |
10 | 16 | This package can be added with the julia command: |
11 | 17 | ```julia |
12 | | -]add PETSc |
| 18 | +julia>]add PETSc |
13 | 19 | ``` |
14 | 20 | The installation can be tested with |
15 | 21 | ```julia |
16 | | -]test PETSc |
| 22 | +julia>]test PETSc |
17 | 23 | ``` |
18 | 24 |
|
19 | 25 | ## PETSc binaries |
20 | 26 |
|
21 | | -By default, the package uses a pre-built binary of (see [PETSc_jll](https://github.com/JuliaBinaryWrappers/PETSc_jll.jl)) along with a default installation of `MPI.jl`, so you don't have to install it on your machine. |
| 27 | +By default, the package uses a pre-built binary of PETSc (see [PETSc_jll](https://github.com/JuliaBinaryWrappers/PETSc_jll.jl)) along with a default installation of `MPI.jl`, so you don't have to install it on your machine. |
22 | 28 |
|
23 | | -If you want to use the package with custom builds of the PETSc library, this can be done by specifying the environment variable `JULIA_PETSC_LIBRARY`. This is a colon separated list of paths to custom builds of PETSc; the reason for using multiple builds is to enable single, double, and complex numbers in the same julia session. These should be built against the same version of MPI as used with `MPI.jl` |
| 29 | +If you want to use the package with custom builds of the PETSc library, this can be done by using the function `set_petsclib` which requires you to point to the correct dynamic library (which should be compatible with the MPI version used by `MPI.jl`) |
24 | 30 |
|
25 | | -After setting the variable you should |
26 | 31 | ```julia |
27 | | -]build PETSc |
28 | | -``` |
29 | | -and the library will be persistently set until the next time the build command is issued. |
| 32 | +using PETSc |
30 | 33 |
|
31 | | -To see the currently set library use |
| 34 | +# Create custom library instance |
| 35 | +petsclib = set_petsclib("/path/to/custom/libpetsc.so"; |
| 36 | + PetscScalar=Float64, PetscInt=Int64) |
| 37 | +# Use it like any precompiled library |
| 38 | +PETSc.initialize(petsclib, log_view=true) |
| 39 | +# ... your code ... |
| 40 | +PETSc.finalize(petsclib) |
| 41 | +``` |
| 42 | +To get an overview of available precompiled libraries: |
32 | 43 | ```julia |
33 | | -using PETSc |
34 | | -PETSc.libs |
| 44 | +julia>using PETSc |
| 45 | +julia>[PETSc.petsclibs...] |
35 | 46 | ``` |
| 47 | + |
36 | 48 | ## Windows users |
37 | 49 | The package currently does not work on windows, mainly because `MicrosoftMPI_jll` does not function when used along with the precompiled version used in `PETSc_jll`. Windows users are therefore advised to install the [Windows Subsystem for Linux](https://en.wikipedia.org/wiki/Windows_Subsystem_for_Linux) (WSL) and run PETSc through there. |
38 | 50 |
|
39 | 51 | ## Getting started |
40 | | -The documentation is currently rather minimalistic; yet, if you want to see what is possible have a look at the [examples](./examples/) directory or at the tests in the [test](./test) directory. We do keep the tests up to date, so that is a good starting point. |
| 52 | +The documentation is currently rather minimalistic; yet, if you want to see what is possible have a look at the [examples](./examples/) directory or at the tests in the [test](./test) directory. We do keep the tests up to date, so that is a good starting point. |
| 53 | + |
| 54 | +Note, that we do not have tests in place for the whole library at this stage. The best supported parts are `DMDA`,`DMStag`, `KSP`,`SNES`,`Vec` and `Mat` interfaces, while other parts such as `DMPlex` do not have a high-level interface or tests yet. Users will thus have to rely on the low-level interface. |
0 commit comments