|
5 | 5 | [](https://github.com/gridap/GridapPETSc.jl/actions?query=workflow%3ACI) |
6 | 6 | [](https://codecov.io/gh/gridap/GridapPETSc.jl) |
7 | 7 |
|
8 | | -[Gridap](https://github.com/gridap/Gridap.jl) (Grid-based approximation of partial differential equations in Julia) plugin to use PETSC ([Portable, Extensible Toolkit for Scientific Computation](https://www.mcs.anl.gov/petsc/)). |
9 | | - |
10 | | -## Basic Usage |
11 | | - |
12 | | -```julia |
13 | | -using MPI |
14 | | -using Gridap |
15 | | -using GridapPETSc |
16 | | -using SparseArrays |
17 | | - |
18 | | -MPI.Init() |
19 | | -GridapPETSc.Init() |
20 | | - |
21 | | -A = sparse([1,2,3,4,5],[1,2,3,4,5],[1.0,2.0,3.0,4.0,5.0]) |
22 | | -b = ones(A.n) |
23 | | -x = similar(b) |
24 | | -ps = PETScSolver() |
25 | | -ss = symbolic_setup(ps, A) |
26 | | -ns = numerical_setup(ss, A) |
27 | | -solve!(x, ns, b) |
28 | | - |
29 | | -GridapPETSc.Finalize() |
30 | | -MPI.Finalize() |
31 | | -``` |
32 | | - |
33 | | -## Usage in a Finite Element computation |
34 | | - |
35 | | -```julia |
36 | | -using MPI |
37 | | -using Gridap |
38 | | -using GridapPETSc |
39 | | - |
40 | | -tol = 1e-10 |
41 | | - |
42 | | -MPI.Init() |
43 | | -GridapPETSc.Init(["-ksp_rtol","$tol"]) |
44 | | - |
45 | | -domain = (0,1,0,1,0,1) |
46 | | -cells = (10,10,10) |
47 | | -model = CartesianDiscreteModel(domain,cells) |
48 | | - |
49 | | -order = 1 |
50 | | -V = TestFESpace( model, |
51 | | - ReferenceFE(lagrangian,Float64,order), |
52 | | - conformity=:H1, dirichlet_tags="boundary" ) |
53 | | -U = TrialFESpace(V) |
54 | | - |
55 | | -Ω = Triangulation(model) |
56 | | - |
57 | | -degree = 2*order |
58 | | -dΩ = Measure(Ω,degree) |
59 | | - |
60 | | -f(x) = x[1]*x[2] |
61 | | - |
62 | | -a(u,v) = ∫( ∇(v)⋅∇(u) )*dΩ |
63 | | -l(v) = ∫( v*f )*dΩ |
64 | | - |
65 | | -ass = SparseMatrixAssembler(SparseMatrixCSR{0,PetscReal,PetscInt},U,V) |
66 | | -op = AffineFEOperator(a,l,ass) |
67 | | - |
68 | | -ls = PETScSolver() |
69 | | -solver = LinearFESolver(ls) |
70 | | - |
71 | | -uh = solve(solver,op) |
72 | | - |
73 | | -GridapPETSc.Finalize() |
74 | | -MPI.Finalize() |
75 | | -``` |
| 8 | +[Gridap](https://github.com/gridap/Gridap.jl) plugin to use PETSC ([Portable, Extensible Toolkit for Scientific Computation](https://www.mcs.anl.gov/petsc/)). |
76 | 9 |
|
77 | 10 | ## Installation |
78 | 11 |
|
79 | | -**GridPETSc** itself is installed when you add and use it into another project. |
80 | | - |
81 | | -Please, ensure that your system fulfills the requirements. |
82 | | - |
83 | | -To include into your project form Julia REPL, use the following commands: |
84 | | - |
85 | | -``` |
86 | | -pkg> add GridapPETSc |
87 | | -julia> using GridapPETSc |
88 | | -``` |
89 | | - |
90 | | -If, for any reason, you need to manually build the project, write down the following commands in Julia REPL: |
91 | | -``` |
92 | | -pkg> add GridapPETSc |
93 | | -pkg> build GridapPETSc |
94 | | -julia> using GridapPETSc |
95 | | -``` |
96 | | - |
97 | | -### Requirements |
98 | | - |
99 | | -`GridapPETSc` julia package requires `PETSC` library ([Portable, Extensible Toolkit for Scientific Computation](https://www.mcs.anl.gov/petsc/)) and `OPENMPI` to work correctly. `PETSc` library can be manually installed in any path on your local machine. In order to succesfull describe your custom installation to be located by `GridapPETSc`, you must export `PETSC_DIR` and `PETSC_ARCH` environment variables. If this environment variables are not available, `GridapPETSc` will try to find the library in the usual linux user library directory (`/usr/lib`). |
100 | | - |
101 | | -`PETSC_DIR` and `PETSC_ARCH` are a couple of variables that control the configuration and build process of PETSc: |
102 | | - |
103 | | - - `PETSC_DIR`: this variable should point to the location of the PETSc installation that is used. Multiple PETSc versions can coexist on the same file-system. By changing `PETSC_DIR` value, one can switch between these installed versions of PETSc. |
104 | | - - `PETSC_ARCH`: this variable gives a name to a configuration/build. Configure uses this value to stores the generated config makefiles in `${PETSC_DIR}/${PETSC_ARCH}`. Make uses this value to determine this location of these makefiles which intern help in locating the correct include and library files. |
105 | | - |
106 | | -Thus one can install multiple variants of PETSc libraries - by providing different `PETSC_ARCH` values to each configure build. Then one can switch between using these variants of libraries from make by switching the `PETSC_ARCH` value used. |
107 | | - |
108 | | -If configure doesn't find a `PETSC_ARCH` value (either in env variable or command line option), it automatically generates a default value and uses it. Also - if make doesn't find a `PETSC_ARCH` env variable - it defaults to the value used by last successful invocation of previous configure. `PETSC_ARCH` value can be an empty string too. |
109 | | - |
110 | | -#### Basic PETSc installation on Debian-based systems |
111 | | - |
112 | | -`PETSc` can be obtained from the default repositories of your Debian-based OS by means of `apt` tool. |
113 | | - |
114 | | -Basic `PETSc` installation in order to use it from `GridapPETSc` julia package is as follows: |
115 | | - |
116 | | -``` |
117 | | -$ sudo apt-get update |
118 | | -$ sudo apt-get install openmpi-bin petsc-dev |
119 | | -``` |
120 | | - |
121 | | -## Continuous integration |
122 | | - |
123 | | -In order to take advantage of `GridapPETSc` julia package during continuous integration, you must ensure that the requirements are fullfilled in the CI environment. |
124 | | - |
125 | | -If your CI process is based on `Travis-CI` you can add the following block at the beginning of your `.travis.yml` file: |
| 12 | +`GridapPETSc` julia package requires the `PETSC` library ([Portable, Extensible Toolkit for Scientific Computation](https://www.mcs.anl.gov/petsc/)) and `MPI` to work correctly. You have two main options to install these dependencies. |
126 | 13 |
|
127 | | -``` |
128 | | -addons: |
129 | | - apt: |
130 | | - update: true |
131 | | - packages: |
132 | | - - openmpi-bin |
133 | | - - petsc-dev |
134 | | -``` |
| 14 | +- **Do nothing [recommended in most cases].** Use the default precompiled `MPI` installation provided by [`MPI.jl`](https://github.com/JuliaParallel/MPI.jl) and the pre-compiled `PETSc` library provided by [`PETSc_jll`](https://github.com/JuliaBinaryWrappers/PETSc_jll.jl). This will happen under the hood when you install `GridapPETSc`. You can also force the installation of these default dependencies by setting the environment variables `JULIA_MPI_BINARY` and `JULIA_PETSC_LIBRARY` to empty values. |
135 | 15 |
|
136 | | -If your CI process is based on `GitHub Actions` you can add the following block at the beginning of the test steps in the `.github/workflows/ci.yml` file: |
| 16 | +- **Choose a specific installation of `MPI` and `PETSc` available in the system [recommended in HPC clusters]**. |
| 17 | + - First, choose a `MPI` installation. See the documentation of [`MPI.jl`](https://github.com/JuliaParallel/MPI.jl) for further details. An easy way to achieve this is to create the environment variable `JULIA_MPI_BINARY` containing the path to the `MPI` binary. |
| 18 | + - Second, choose a `PETSc` installation. To this end, create an environment variable `JULIA_PETSC_LIBRARY` containing the path to the dynamic library object of the `PETSC` installation (i.e., the `.so` file in linux systems). **Very important: The chosen `PETSc` lirbary needs to be configured with the `MPI` installation considered in previous step**. |
137 | 19 |
|
138 | | -``` |
139 | | -steps: |
140 | | - - name: Install dependencies |
141 | | - run: sudo apt-get update; sudo apt-get install openmpi-bin petsc-dev |
142 | | -``` |
143 | 20 |
|
144 | 21 | ## Notes |
145 | 22 |
|
146 | | -`GridapPETSc` default sparse matrix format is 0-based compressed sparse row. This types of sparse matrix can be described by `SparseMatrixCSR{0,PetscReal,PetscInt}` and `SymSparseMatrixCSR{0,PetscReal,PetscInt}`.These types of matrix are implemented in the [SparseMatricesCSR](https://gridap.github.io/SparseMatricesCSR.jl/stable/)) julia package. |
| 23 | +`GridapPETSc` default sparse matrix format is 0-based compressed sparse row. This types of sparse matrix can be described by `SparseMatrixCSR{0,PetscReal,PetscInt}` and `SymSparseMatrixCSR{0,PetscReal,PetscInt}` implemented in the [SparseMatricesCSR](https://gridap.github.io/SparseMatricesCSR.jl/stable/) Julia package. |
0 commit comments