README.md


# AlgTools

Author: Tuomo Valkonen <tuomov@iki.fi>

This repository contains some general utility routines and tools for doing
iterative algorithms in Julia:

  * Tools to facilitate working with `Channel`s
  * Linked lists and writing them to log files.
  * Structs: iteration, field replacement
  * Calculation of norms, dot products, projections
  * Conditional thread execution macros
  * Template for conveniently writing iterative algorithms using `do`-block anonymous functions as algorithm steps, with visualisation/verbosity implemented generally in iterator.

  The code is used by [ImageTools][] and both, for example, by <http://dx.doi.org/10.5281/zenodo.3659180>.

## Installation

To install this package, first clone the repository with [Mercurial](https://www.mercurial-scm.org/):

```console
$ hg clone https://tuomov.iki.fi/repos/AlgTools/
```

(Canonical public repository URL indicated here.)
Then add the repository to Julia with `Pkg.develop`:

```console
julia>] develop LOCATION_OF/AlgTools/
```

Here replace `LOCATION_OF/AlgTools` with path where you cloned AlgTools. (If you did not change directory after cloning, simply use `AlgTools`.)
Afterwards, you may use the package with:

```console
julia> using AlgTools
```

This package is not and is not planned to be available via `Pkg.add` as it is based on the worst and must unusable version control system ever invented: Git.

## Iterative algorithms in a functional fashion

The package includes `simple_iterate` which helps separating the computational step of iterative algorithms from visualisation and other reporting routines.
It is merely intended to serve as a template, as different applications require different visualisation routines to be implemented in a replacement of `simple_iterate`; in particular [ImageTools][] implements its own version.

The approach is heavily indebted to functional programming.
The computational step is to be implemented as a `do`-block anonymous function.
That function gets passed another function `verbose` as a parameter.
To (potentially) report the current status, the computational step only needs to call `verbose` with yet another function as a parameter. Whether the status is actually reported—and whether it needs to be calculated—is decided by `verbose`, and its parameter called as needed.

### Simple example

```julia
using AlgTools.Iterate

params = (verbose_iter = 10, maxiter = 100,)

begin
    local x = 1
    simple_iterate(params) do verbose
        # This is our computational step, as an anonymous
        # `do`-block function. It has one parameter: `verbose`,
        # itself a function.
        x = x + √x
        verbose() do
            # This is another anonymous function that will
            # only get called when decided by `verbose`.
            # If we do get called, return current value
            return x, nothing
        end
    end
end
```
This will output
```
10/100 J=31.051164
20/100 J=108.493699
30/100 J=234.690039
40/100 J=410.056327
50/100 J=634.799262
60/100 J=909.042928
70/100 J=1232.870172
80/100 J=1606.340254
90/100 J=2029.497673
100/100 J=2502.377071
```

  [ImageTools]: https://tuomov.iki.fi/software/ImageTools/