MaterialReconstruction.jl

MaterialReconstruction.jl package can be used to recreate binary arrays (also called two-phase systems in this documentation) from a set of descriptors known as correlation functions using a technique called simulated annealing. It works in conjunction with packages CorrelationFunctions.jl and CorrelationsTrackers.jl.

This package is quite configurable which means you can decide which correlation functions to take into account, which cooldown schedule to use etc.

Look at this minimal example to see how MaterialReconstruction.jl can be used:

using CorrelationFunctions
using CorrelationTrackers
using MaterialReconstruction
using Images
using FileIO
using Random

Random.seed!(123)
# Load a binary array we want to reconstruct
array = load("images/value-noise.png") .|> Bool
# Choose correlation functions we want to track (S2 for void phase, L2 for both phases)
functions = [S2Tracker(false), L2Tracker(false), L2Tracker(true)]
# Create an instance of CorrelationTracker type. Correlation functions are calculated
# with periodic boundary conditions.
target = CorrelationTracker(array; tracking = functions, periodic = true)

# Initialize an array to be reconstructed
system = CorrelationTracker(target |> initialize_spheres, target)
# Create an instance of Furnace. T0 is an initial temperature
furnace = Furnace(system, target; T0 = 2e-5)
# Choose a cost function.
# (More about Čapek cost function in the section "Cost functions")
cost = čapek_cost(system, target, 0.4)
# Choose a modifier (more in the section "Samplers and modifiers")
modifier = Flipper(InterfaceSampler())
# Choose a cooldown schedule (more in the section "Cooldown schedules")
cooldown = aarts_korst_cooldown(n = 100, λ = 0.01)

# Measure initial value of the cost function
cost1 = cost(target, system)

# This is a kludge used to work around impossibility of reassigning a variable
# in the loop in examples generated by Documenter.jl
function annealing_step!(f)
    f[] = annealing_step(f[];
                         cost     = cost,
                         modifier = modifier,
                         cooldown = cooldown)
end

# Run 5000 annealing steps. Usually you have to repeat this loop a few million times.
f = Ref(furnace)
for i in 1:5000
    annealing_step!(f)
end

# Measure final value of the cost function
cost2 = cost(target, system)
cost1, cost2

(0.08031552774628573, 0.05330782954198182)

As you see, the cost function decreases after 5000 iterations of the process. More illustrative examples are in the section Examples. Each aspect of MaterialReconstruction.jl API is described in a dedicated section.

Cost functions

Cost functions are the functions which are minimized during simulated annealing. Usually, we have two binary arrays, one of them is fixed (the target array) and the other is changed during annealing. An annealing process stops when the value of the cost function becomes small enough which means two arrays are "similar" to each other. A cost function takes two CorrelationTracker objects (which are our arrays + a set of correlation functions calculated for those arrays) and returns a real number which specifies how similar those arrays are. Usually, this similarity is measured by comparing the values of correlation functions. The following cost functions are defined in this package:

MaterialReconstruction.euclid_mean — Function

euclid_mean(data1 :: CorrelationData, data2 :: CorrelationData)
euclid_mean(data1 :: AbstractArray, data2 :: AbstractArray)

Calculate squared euclidean distance between values of two correlation functions (represented as CorrelationData object) or two systems (represented as AbstractArray object). The values are averaged along all directions before calculation.

Function name	Optional?	Default definition
`update_pre!`	Yes	`nothing`
`update_post!`	Yes	`nothing`
`sample`	No