Skip to content

Commit

Permalink
Update README for fast load
Browse files Browse the repository at this point in the history
  • Loading branch information
@tobydriscoll
tobydriscoll committed May 24, 2022
1 parent 65d37bc commit 1c23fe9
Showing 1 changed file with 62 additions and 24 deletions.
86 changes: 62 additions & 24 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -19,41 +19,79 @@ These are core functions for the text *Fundamentals of Numerical Computation* by

The process will take a while. In order to flatten the learning curve, this package loads many other standard numerical and plotting packages and makes them available, so there is a lot of code to install and compile.
5. Hit the backspace (delete on Mac) key to go back to the main Julia prompt. **Steps 3-5 should only need to be done once per Julia installation.**
6. In order to use the functions, in each new Julia session you must enter

```julia
using FundamentalsNumericalComputation
```
## Usage

After this completes, all the text's functions can be accessed with the prefix `FNC`. E.g., `FNC.lufact`, `FNC.rk23`, etc.
In order to use the functions, in each new Julia session you must enter

## Usage
```julia
using FundamentalsNumericalComputation
```

None of the functions are exported, so they must all be prefixed with the package name. However, the constant `FNC` is set as an alias to the package name to make typing more reasonable, e.g., `FNC.lufact`, `FNC.rk23`, etc.

There is a bare-bones [documentation site][docs-stable-url], but it only gives summaries of the documentation strings that are found in the text. The textbook is meant to be the real guide.

## Startup speed

After installation, importing the package with a `using` statement should only take 5-10 seconds in Julia 1.6 or later. The first plot created in a Julia session may take 20-60 seconds to appear. This is a well-known irritant in the Julia ecosystem, and progress is steadily being made toward reducing the lag. In the meantime, there are a few options available for power users.

### PackageCompiler

The [`PackageCompiler`](https://julialang.github.io/PackageCompiler.jl/) package allows you to compile a new version of the Julia binary to get better startup performance. It's not too hard to use, but it helps if you are comfortable with command line/terminal interfaces.

### Minimal package version

You can speed up loading time by installing a special branch of this package. At the prompt, type the `]` character to enter package mode. If you already installed the default version, enter

```julia
rm FundamentalsNumericalComputation
```

None of the functions are exported, so they must all be prefixed with the package name. However, the constant `FNC` is set as an alias to the package name to make typing more reasonable.
Then enter

There is a bare-bones [documentation site][docs-stable-url], but it only gives summaries of the documentation strings. The textbook is meant to be the real guide.
```julia
add https://github.com/fncbook/FundamentalsNumericalComputation.jl#fast-load
```

### Startup speed
Now, each import of this package should take ten seconds or less. However, you will need to manually install and then load packages in order to run the demos and solve many of the exercises in the book. (This is how Julia is normally used in practice.) In particular, only `LinearAlgebra`, `Polynomials`, `SparseArrays`, and a few packages for loading files and displaying output are provided. Other packages used in the text, and their key dependents, are given in the following table.

After installation, importing the package with a `using` statement should only take 5-10 seconds in Julia 1.6 or later. The first plot created in a Julia session may take 20-60 seconds to appear. This is a well-known irritant in the Julia ecosystem, and progress is steadily being made toward reducing the lag. In the meantime, power users might investigate using [`PackageCompiler`](https://julialang.github.io/PackageCompiler.jl/dev/) to get better startup performance.
| Package name | Key dependent functions |
| :---------------------- | :-------------------------------- |
| `Arpack` | `eigs` |
| `Dierckx` | `Splline1D` |
| `DifferentialEquations` | `solve` |
| `FFTW` | `fft` |
| `GraphRecipes` | `graphplot` |
| `Images` | image loading and display, `Gray` |
| `IncompleteLU` | `iLU` |
| `IterativeSolvers` | `gmres`, `minres`, `cg` |
| `LinearMaps` | `LinearMap` |
| `MatrixDepot` | `matrixdepot` |
| `NLsolve` | `nlsolve` |
| `Plots` | `plot`, `scatter`, `contour` |
| `Preconditioners` | `DiagonalPreconditioner` |
| `QuadGK` | `quadgk` |
| `SpecialFunctions` | `besselj`, `gamma` |
| `TestImages` | `testimage` |

## Alternatives
## Alternative numerical packages

These codes are for instructional purposes. They are not recommended for applications. Compared to superior alternatives, they lack generality, efficiency, and robustness to syntax and more subtle mistakes. My personal recommendations for preferable alternatives are as follows. Most of them are demonstrated in the textbook.

| Problem type | Associated Julia packages |
|-----------------|---------------|
| Linear system / least squares | [`LinearAlgebra`](https://docs.julialang.org/en/v1/stdlib/LinearAlgebra/#man-linalg) (standard library) |
| Sparse matrix | [SparseArrays](https://docs.julialang.org/en/v1/stdlib/SparseArrays/#Sparse-Arrays), [IterativeSolvers](https://iterativesolvers.julialinearalgebra.org/stable/), [Arpack](https://arpack.julialinearalgebra.org/stable/), [Preconditioners](https://github.com/mohamed82008/Preconditioners.jl) |
| Polynomial interpolation/approximation | [Polynomials](https://juliamath.github.io/Polynomials.jl/stable/), [ApproxFun](https://juliaapproximation.github.io/ApproxFun.jl/stable/) |
| Polynomial roots | [Polynomials](https://juliamath.github.io/Polynomials.jl/stable/#Root-finding-1) |
| Rootfinding | [NLsolve](https://github.com/JuliaNLSolvers/NLsolve.jl) |
| Finite differences | [FiniteDifferences](https://juliadiff.org/FiniteDifferences.jl/latest/), [FiniteDiff](https://github.com/JuliaDiff/FiniteDiff.jl) |
| Integration | [QuadGK](https://juliamath.github.io/QuadGK.jl/stable/) |
| Spline | [Dierckx](https://github.com/kbarbary/Dierckx.jl) |
| [Initial-value problem](https://diffeq.sciml.ai/latest/tutorials/ode_example/#ode_example) | [DifferentialEquations](https://diffeq.sciml.ai/latest/) |
| [Boundary-value problem](https://diffeq.sciml.ai/latest/tutorials/bvp_example/#Boundary-Value-Problems) | [DifferentialEquations](https://diffeq.sciml.ai/latest/) |
| Method of lines | [MethodOfLines](https://methodoflines.sciml.ai/dev/) (still under development)
| Problem type | Associated Julia packages |
| ------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Linear system / least squares | [`LinearAlgebra`](https://docs.julialang.org/en/v1/stdlib/LinearAlgebra/#man-linalg) (standard library) |
| Sparse matrix | [SparseArrays](https://docs.julialang.org/en/v1/stdlib/SparseArrays/#Sparse-Arrays), [IterativeSolvers](https://iterativesolvers.julialinearalgebra.org/stable/), [Arpack](https://arpack.julialinearalgebra.org/stable/), [Preconditioners](https://github.com/mohamed82008/Preconditioners.jl) |
| Polynomial interpolation/approximation | [Polynomials](https://juliamath.github.io/Polynomials.jl/stable/), [ApproxFun](https://juliaapproximation.github.io/ApproxFun.jl/stable/) |
| Polynomial roots | [Polynomials](https://juliamath.github.io/Polynomials.jl/stable/#Root-finding-1) |
| Rootfinding | [NLsolve](https://github.com/JuliaNLSolvers/NLsolve.jl) |
| Finite differences | [FiniteDifferences](https://juliadiff.org/FiniteDifferences.jl/latest/), [FiniteDiff](https://github.com/JuliaDiff/FiniteDiff.jl) |
| Integration | [QuadGK](https://juliamath.github.io/QuadGK.jl/stable/) |
| Spline | [Dierckx](https://github.com/kbarbary/Dierckx.jl) |
| [Initial-value problem](https://diffeq.sciml.ai/latest/tutorials/ode_example/#ode_example) | [DifferentialEquations](https://diffeq.sciml.ai/latest/) |
| [Boundary-value problem](https://diffeq.sciml.ai/latest/tutorials/bvp_example/#Boundary-Value-Problems) | [DifferentialEquations](https://diffeq.sciml.ai/latest/) |
| Method of lines | [MethodOfLines](https://methodoflines.sciml.ai/dev/) (still under development) |


## License
Expand Down

0 comments on commit 1c23fe9

Please sign in to comment.