FunctionTabulations

This package is a wrapper around Interpolations.jl to compute interpolation tables (FunctionTabulations) for functions of up to three variables with support for Unitful.

This package stems from the common need in physics research projects to tabulate slow functions. With this package, it becomes possible to easily compute the values of a function and tabulate its values for up to three variables.

Installation

using Pkg; Pkg.add("FunctionTabulations")

Usage: 1D FunctionTabulations

Simple usage

To compute and load the tabulation of a function with one variable, it is necessary to use create_tabulation_1D:

using FunctionTabulations

func_1D(x) = sin(x)

sin_tabulation = create_tabulation_1D(func_1D, xmin = 0.0, xmax = 3.0, npoints = 100) # produces a file called `func_1D_data.jld2`

isapprox(sin(3.0), sin_tabulation(3.0), rtol=1e-3)

It is always necessary to specify the function to be tabulated, the interval and the number of points of the tabulation grid. The routine will compute npoints values of the function in the range xmin:xmax, save the table in a .jld2 file, and return the interpolating function of the tabulated data. If a proper .jld2 file already exists for that function, and it was computed in the same x range with the same number of points npoints, it will automatically be loaded on subsequent calls of compute_tabulation_1D.

Logarithmic scale

Sometimes, it is more advantageous to tabulate a function using a logarithmic scale. For example, a function y=f(x) might display a more linear trend when the x or f(x) axis is expressed in logarithmic (log10) scale. In this case, it is possible to ask the routine to tabulate or interpolate that axis in logarithmic scale. For example, given the function f(x)=10^x, it is more advantageous to consider the f(x) axis in logarithmic scale for the interpolation:

func_1D(x) = 10^x

func_1D_tabulation = create_tabulation_1D(func_1D, xmin = 0.0, xmax = 3.0, npoints = 100, f_scale=:log10)

isapprox(func_1D(3.0), func_1D_tabulation(3.0), rtol=1e-3)

On the other hand, a function which needs to be interpolated in a wide range of x and does not vary harshly with x may benefit from the option x_scale=:log10.

Unitful support

FunctionTabulations.jl supports Unitful.jl. It is possible to tabulate functions which have variables of the Quantity type, and/or return quantities. This means that units of measurement are fully supported.

using Unitful

func_1d(x) = x^2

itp_1d_1 = create_tabulation_1D(
    func_1d,
    custom_name = "1d_1",
    xmin = 0.0u"m",
    xmax = 3.0u"m",
    npoints = 100,
    x_scale = :linear,
    f_scale = :linear
)

isapprox(itp_1d_1(2.0u"m"), func_1d(2.0u"m"), rtol = 1e-3)
    

In the case of a tabulation with units of measurement, the unit of the result of the tabulated function is the one returned by f(xmin). Nontheless, it supports automatic unit conversion for the input variables:

func_1d(x) = x^2

itp_1d_1 = create_tabulation_1D(
    func_1d,
    custom_name = "1d_1",
    xmin = 0.0u"m",
    xmax = 3.0u"m",
    npoints = 100,
    x_scale = :linear,
    f_scale = :linear
)

isapprox(itp_1d_1(2.0u"m"), itp_1d_1(200.0u"cm"), rtol = 1e-3)
    

Save location

It is possible to specify the folder where to save/load the interpolation using the option jld_base_path. Furthermore it is possible to specify the name of the file in which the interpolation will be stored using the option custom_name. Please note that the suffix _data.jld2 will always be appended to the filename when the tabulation is stored.

func_1d(x) = sin(x)

itp_1d_2 = create_tabulation_1D(
    func_1d,
    jld_base_path = "interpolations",
    custom_name = "1d_2",
    xmin = 0.0,
    xmax = 3.0,
    npoints = 100,
) 
# will generate a file called "1d_2_data.jld2" in the folder "interpolations". 
# If the folder doesn't exist, the routine will create it.

Interpolation options

It is possible to customize the behaviour of the interpolation of the tabulated grid using interpolation_type and extrapolation_bc. The default interpolation method is a linear interpolation (:linear), but it is also possible to use a cubic spline (:cubic). Furthermore, it is possible to specify the behaviour outside of the tabulation domain (xmin, xmax) using extrapolation_bc. The default behaviour is to throw an exception, but it is also possible for to extrapolate linearly:

using Interpolations: Line

func_1d(x) = sin(x)

itp_1d_1 = create_tabulation_1D(
    func_1d,
    xmin = 0.0,
    xmax = 3.0,
    npoints = 100,
    x_scale = :linear,
    f_scale = :linear,
    interpolation_type = :linear,
    extrapolation_bc = Line,
)

For more information about the extrapolation conditions, see the Interpolations.jl documentation and pass the extrapolation function as the extrapolation_bc argument.

Extra args and kwargs

In case it is necessary to pass further fixed positional arguments or keyword arguments to the tabulated function, create_tabulation_1D will pass the extra args and kwargs to the function to be tabulated:

func_1d(x, a; b) = x^2 + a*b

itp_1d_1 = create_tabulation_1D(
    func_1d,
    2, # the `a` positional argument 
    xmin = 0.0,
    xmax = 3.0,
    npoints = 100,
    b=1, # the `b` positional argument
)

isapprox(itp_1d_1(2.0), func_1d(2.0, 2; b=1), rtol = 1e-3)

Storing metadata

It is possible to store some metadata in the tabulation archive, by specifying the metadata keyword argument. metadata has to be provided in the form of a Dict{String, Any}. By default, when loading a tabulation, if some metadata is provided it will be compared against the stored metadata through the equality metadata == stored_metadata. In case more articulated metadata validation is required, it is possible to pass a validate_metadata_fn function, which will be responsible of metadata validation.

func_1d(x) = sin(x)

function metadata_validation_fn(metadata, loaded_metadata)
    return metadata["a"] == loaded_metadata["a"]
end

itp_1d_1 = create_tabulation_1D(
    func_1d,
    xmin = 0.0,
    xmax = 3.0,
    npoints = 100,
    x_scale = :linear,
    f_scale = :linear,
    metadata = Dict{String, Any}("a"=>1),
    metadata_validation_fn = metadata_validation_fn
) # create the tabulation

itp_1d_1_loaded = create_tabulation_1D(
    func_1d,
    xmin = 0.0,
    xmax = 3.0,
    npoints = 100,
    x_scale = :linear,
    f_scale = :linear,
    metadata = Dict{String, Any}("a"=>1),
    metadata_validation_fn = metadata_validation_fn
) # reload the tabulation

While the library used for storing the tabulations (JLD2) should be able to serialise any dictionary passed as metadata, it is up to the user to properly create and validate the metadata.

Usage: 2D FunctionTabulations & 3D FunctionTabulations

2D FunctionTabulations and 3D FunctionTabulations have a similar syntax, with extra parameters for the y and z variables:

func_2d(x, y) = sin(x) * sin(y)

itp_2d_1 = create_tabulation_2D(
    func_2d,
    xmin = 0.0,
    xmax = 1.0,
    ymin = 0.0,
    ymax = 2.0,
    npoints_x = 100,
    npoints_y = 200,
    x_scale = :linear,
    y_scale = :linear,
    f_scale = :linear
)
isapprox(itp_2d_1(1.0, 1.3), func_2d(1.0, 1.3), rtol = 1e-3)

func_3d(x, y, z) = x * y + z

itp_3d_1 = create_tabulation_3D(
    func_3d,
    xmin = 0.0,
    xmax = 1.0,
    ymin = 0.0,
    ymax = 2.0,
    zmin = 0.0,
    zmax = 3.0,
    npoints_x = 100,
    npoints_y = 200,
    npoints_z = 200,
    x_scale = :linear,
    y_scale = :linear,
    z_scale = :linear,
    f_scale = :linear
)

isapprox(itp_3d_1(1.0, 1.3, 2.5), func_3d(1.0, 1.3, 2.5), rtol = 1e-3)