Skip to content

Commit c91ac40

Browse files
RalphASRalphAS
committed
add online documentation
1 parent 5bb13f6 commit c91ac40

File tree

5 files changed

+170
-7
lines changed

5 files changed

+170
-7
lines changed

‎.github/workflows/CI.yml‎

Lines changed: 35 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -1,33 +1,40 @@
11
name: CI
2+
concurrency:
3+
group: build-${{ github.event.pull_request.number || github.ref }}
4+
cancel-in-progress: true
25
on:
36
pull_request:
47
push:
58
branches:
69
- master
710
tags: '*'
811
jobs:
12+
pre_job:
13+
# continue-on-error: true # Uncomment once integration is finished
14+
runs-on: ubuntu-latest
15+
# Map a step output to a job output
16+
outputs:
17+
should_skip: ${{ steps.skip_check.outputs.should_skip }}
18+
steps:
19+
- id: skip_check
20+
uses: fkirc/skip-duplicate-actions@v5
921
test:
1022
name: Julia ${{ matrix.version }} - ${{ matrix.os }} - ${{ matrix.arch }} - ${{ github.event_name }}
1123
runs-on: ${{ matrix.os }}
1224
strategy:
1325
fail-fast: false
1426
matrix:
1527
version:
16-
- '1.6'
28+
- 'lts'
1729
- '1'
1830
- 'nightly'
1931
os:
2032
- ubuntu-latest
21-
- macOS-latest
22-
- windows-latest
23-
arch:
24-
- x64
2533
steps:
2634
- uses: actions/checkout@v4
27-
- uses: julia-actions/setup-julia@v1
35+
- uses: julia-actions/setup-julia@v2
2836
with:
2937
version: ${{ matrix.version }}
30-
arch: ${{ matrix.arch }}
3138
- uses: actions/cache@v3
3239
env:
3340
cache-name: cache-artifacts
@@ -44,3 +51,24 @@ jobs:
4451
- uses: codecov/codecov-action@v3
4552
with:
4653
files: lcov.info
54+
fail_ci_if_error: false
55+
docs:
56+
name: Documentation
57+
runs-on: ubuntu-latest
58+
steps:
59+
- uses: actions/checkout@v4
60+
- uses: julia-actions/setup-julia@v2
61+
with:
62+
version: '1'
63+
- uses: julia-actions/cache@v2
64+
- uses: julia-actions/julia-buildpkg@v1
65+
- uses: julia-actions/julia-docdeploy@v1
66+
env:
67+
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
68+
DOCUMENTER_KEY: ${{ secrets.DOCUMENTER_KEY }}
69+
- run: |
70+
julia --project=docs -e '
71+
using Documenter: DocMeta, doctest
72+
using IterativeRefinement
73+
DocMeta.setdocmeta!(IterativeRefinement, :DocTestSetup, :(using IterativeRefinement); recursive=true)
74+
doctest(IterativeRefinement)'

‎docs/Project.toml‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
[deps]
2+
Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
3+
IterativeRefinement = "bcb6b82e-7479-5933-8c8e-2e0b909ee6a3"
4+
LinearAlgebra = "37e2e46d-f89d-539d-b4ee-838fcccc9c8e"
5+
6+
[compat]
7+
Documenter = "~0.21"

‎docs/make.jl‎

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
using Documenter, IterativeRefinement, LinearAlgebra
2+
3+
makedocs(
4+
modules = [IterativeRefinement],
5+
format = Documenter.HTML(prettyurls = get(ENV, "CI", nothing) == true),
6+
sitename = "IterativeRefinement.jl",
7+
pages = ["Overview" => "index.md",
8+
"Library" => "library.md"
9+
]
10+
)
11+
12+
# or maybe just the pkg site?
13+
deploydocs(
14+
repo = "github.com/RalphAS/IterativeRefinement.jl.git",
15+
)

‎docs/src/index.md‎

Lines changed: 96 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,96 @@
1+
# IterativeRefinement
2+
3+
This package is an implementation of multi-precision iterative refinement for
4+
certain dense-matrix linear algebra problems.
5+
6+
## Background
7+
The purpose of iterative refinement (IR) is to improve the accuracy of a
8+
solution. If `x` is the exact solution of `A*x=b`, a simple solve of
9+
the form `y = A \ b` will have a relative forward error
10+
(`norm(y-x)/norm(x)`) of approximately `ϵ * O(n) * cond(A)` where `ϵ`
11+
is the unit roundoff error in the standard precision. Iterative
12+
refinement with higher precision residuals can reduce this to
13+
`ϵ * O(n)`, as long as the matrix `A` is not very badly conditioned
14+
relative to `ϵ`.
15+
16+
Why not do everything in high precision? The factorization step is
17+
typically *very* expensive (`O(n^3)`) in high precision, whereas the
18+
residual computation is relatively cheap (`O(n^2)`). Furthermore, IR
19+
schemes often provide useful error bounds.
20+
21+
For typical use, one would have a basic working precision of `Float64`
22+
(`ϵ = 2.2e-16`), so that fast LAPACK/BLAS routines dominate the runtime.
23+
`rfldiv` will then (by default) use `BigFloat` for residuals.
24+
One might alternatively use `Double64` from
25+
[DoubleFloats.jl](https://github.com/JuliaMath/DoubleFloats.jl)
26+
or `Float128` from
27+
[Quadmath.jl](https://github.com/JuliaMath/Quadmath.jl)
28+
29+
# Linear systems
30+
31+
This package provides a function `rfldiv`, which
32+
handles linear matrix-vector problems of the form
33+
34+
`A x = b`.
35+
36+
## Basic Usage
37+
```julia
38+
julia> using LinearAlgebra, IterativeRefinement
39+
julia> x, bnorm, bcomp = rfldiv(A,b)
40+
```
41+
This provides an accurate solution vector `x` and estimated bounds
42+
on norm-wise and component-wise relative error. By default `LU` decomposition
43+
is used.
44+
45+
## Advanced Usage
46+
See the function docstring for details.
47+
48+
If one has several right-hand-sides, one can equilibrate and factor
49+
`A` in advance; see the tests for an example.
50+
51+
## Reference
52+
J.Demmel et al., "Error bounds from extra precise iterative refinement,"
53+
LAPACK Working Note Nr. 165 (2005), also published as
54+
ACM TOMS, 32, 325 (2006). The work
55+
described therein eventually turned into a collection of subroutines
56+
included in some versions of LAPACK. This implementation is based on
57+
the paper; minor modifications were introduced based on experimentation.
58+
To be precise, this package implements Algorithm 3.
59+
60+
# Eigensystems
61+
62+
Additional methods (`rfeigen`) are provided for improving estimates of
63+
eigenvalue/subspace pairs of the form
64+
65+
`A X = X λ`.
66+
67+
For a simple eigenvalue, `X` is the corresponding eigenvector, and
68+
the user provides coarse estimates of both. In the case of
69+
multiple or defective eigenvalues, columns of `X` are generators for the
70+
corresponding invariant subspace, and the user provides a Schur decomposition
71+
with a list of indices for the cluster of interest.
72+
73+
Problem-specific error bound estimates are not yet provided for eigensystems.
74+
75+
## Basic Usage
76+
### isolated eigenvalue
77+
```julia
78+
julia> using LinearAlgebra, IterativeRefinement, Quadmath
79+
julia> E = eigen(A)
80+
julia> j = your_index_selection()
81+
julia> λrefined, xrefined = rfeigen(A, E.vectors[:,j], E.values[j], Float128)
82+
```
83+
84+
### eigenvalue cluster
85+
```julia
86+
julia> using LinearAlgebra, IterativeRefinement, Quadmath
87+
julia> S = schur(A)
88+
julia> S = LinearAlgebra.Schur{ComplexF64}(S) # if eltype of A is real
89+
julia> idx = findall(abs.(S.values .- target) .< 0.1)
90+
julia> λrefined, Vrefined = rfeigen(A, S, idx, Float128)
91+
```
92+
93+
## Reference
94+
J.J.Dongarra, C.B.Moler, and J.H.Wilkinson, "Improving the accuracy of computed
95+
eigenvalues and eigenvectors," SIAM J. Numer. Anal. 20, 23-45 (1983).
96+

‎docs/src/library.md‎

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,17 @@
1+
# API
2+
3+
## Linear systems
4+
5+
```@docs
6+
rfldiv
7+
8+
equilibrators
9+
10+
condInfest
11+
```
12+
13+
## Eigensystems
14+
15+
```@docs
16+
rfeigen
17+
```

0 commit comments

Comments
 (0)