API

RheoTimeData(;σ::Vector{T1}, ϵ::Vector{T2}, t::Vector{T3}) where {T1<:Real, T2<:Real, T3<:Real}

RheoTimeData struct contains stress, strain and time data.

If preferred, an instance can be generated manually by just providing the three data vectors in the right order, sampling type will be checked automatically.

Fields

• σ: stress
• ϵ: strain
• t: time
• log: a log of struct's events, e.g. preprocessing

RheoFreqData(Gp::Vector{T1}, Gpp::Vector{T2}, ω::Vector{T3}, log::OrderedDict{Any,Any}) where {T1<:Real, T2<:Real, T3<:Real}

RheoFreqData contains storage modulus, loss modulus and frequency data.

If preferred, an instance can be generated manually by just providing the three data vectors in the right order.

Fields

• Gp: storage modulus
• Gpp: loss modulus
• ω: frequency
• log: a log of struct's events, e.g. preprocessing

gettime(d::RheoTimeData)

returns the time vector.

getstress(d::RheoTimeData)

returns the stress vector if d contains stress data.

getstrain(d::RheoTimeData)

returns the strain vector if d contains strain data.

getfreq(d::RheoFreqData)

returns the frequency ω vector.

getstorage(d::RheoFreqData)

returns the storage modulus vector.

getloss(d::RheoFreqData)

returns the loss modulus vector.

RheoModelClass(;name::String, p::Tuple, G,J,Gp,Gpp, constraint, info, G_ramp)

RheoModelClass is a complex data structure that contains all the relevant data to allow RHEOS to fit models and make predictions once parameters are set. RHEOS possesses already a large number of such data structures to represent common rheological models, such as Maxwell or KelvinVoigt.

Users are not expected to directly manipulate the content of a RheoModelClass object, but will pass it to relevant functions for fitting and numerically evaluating visco-elastic moduli.

The model name and its parameters can however be printed and display on the REPL.

Example

julia> Maxwell

Model name: maxwell

Free parameters: η and k

                ___
            _____| |________╱╲  ╱╲  ╱╲  ___
                _|_|          ╲╱  ╲╱  ╲╱
                  η                  k
               

RheoModel(m::RheoModelClass, nt0::NamedTuple)

RheoModel represents a rheological model with set parameters. They are obtained by fitting a model to data using modelfit, or by specialising the relevant RheoModelClass by prescribing its parameters. Parameters can be provided as a named tuple or keyword arguments.

RheoModel objects can then be used to simulate the response to an arbitrary input using modelpredict, and access the values of the moduli functions.

Example

julia> model = RheoModel(Maxwell, (k=1, η=2.))
[...]

julia> model = RheoModel(Maxwell, k=1, η=2.)
[...]

getparams(m::RheoModel; unicode=true)

getparams return the list of model parameters with their values as a NamedTuple. If unicode is set to false, the unicode symbols are converted their text equivalent.

Example

julia> model = RheoModel(Maxwell, k=1, η=2.)
[...]

julia> getparams(m)
(k = 1.0, η = 2.0)

julia> getparams(m,unicode=false)
(k = 1.0, eta = 2.0)

freezeparams(m::RheoModelClass, nt0::NamedTuple)

Return a new RheoModelClass with some of the parameters frozen to specific values

Arguments

• m: original RheoModelClass
• nt0: named tuple with values for each parameter to freeze

Example

julia> SLS2_mod = freezeparams( SLS2, (G₀=2,η₂=3.5))
[...]

julia> SLS2.G(1,[2,1,2,3,3.5])
3.8796492

julia> SLS2_mod.G(1,[1,2,3])
3.8796492

relaxmod(m[, t, params])

provide access to the relaxation modulus (G) of a given model m. It can be used with a broad range of inputs.

When a time value is provided (or an array of time values), the function returns the corresponding value(s) of the relaxation modulus.

relaxmod(m::RheoModel, time (single value or array))

relaxmod(m::RheoModelClass, time (single value or array), parameters (array, named tupple or keyword parameters))

Examples:

relaxmod(Maxwell, 1, k=1., η=1)

relaxmod(Maxwell, [1,2,3], [1,1])

When no time value is provided, relaxmod returns the relaxation function itself.

relaxmod(m::RheoModel)

relaxmod(m::RheoModelClass, parameters (array, named tupple or keyword parameters))

Examples:

m = RheoModel(Maxwell, k=1., η=1)
G = relaxmod(m)
G([0,1,2])

creepcomp(m[, t, params])

provide access to the creep compliance (J) of a given model m. It can be used with a broad range of inputs.

When a time value is provided (or an array of time values), the function returns the corresponding value(s) of the creep compliance.

creepcomp(m::RheoModel, time (single value or array))

creepcomp(m::RheoModelClass, time (single value or array), parameters (array, named tupple or keyword parameters))

Examples:

creepcomp(Maxwell, 1, k=1., η=1)

creepcomp(Maxwell, [1,2,3], [1,1])

When no time value is provided, creepcomp returns the creep compliance function itself.

creepcomp(m::RheoModel)

creepcomp(m::RheoModelClass, parameters (array, named tupple or keyword parameters))

Examples:

m = RheoModel(Maxwell, k=1., η=1)
J = creepcomp(m)
J([0,1,2])

storagemod(m[, ω, params])

provide access to the storage modulus (G') of a given model m.

When a frequency value is provided (or an array of frequency values), the function returns the corresponding value(s) of the storage modulus.

storagemod(m::RheoModel, frequency (single value or array))

storagemod(m::RheoModelClass, frequency (single value or array), parameters (array, named tupple or keyword parameters))

Examples:

storagemod(Maxwell, 1, k=1., η=1)

storagemod(Maxwell, [1,2,3], [1,1])

When no time value is provided, storagemod returns the storage modulus function itself.

storagemod(m::RheoModel)

storagemod(m::RheoModelClass, parameters (array, named tupple or keyword parameters))

Examples:

m = RheoModel(Maxwell, k=1., η=1)
Gp = storagemod(m)
Gp([0,1,2])

lossmod(m[, ω, params])

provide access to the loss modulus (G'') of a given model m.

When a frequency value is provided (or an array of frequency values), the function returns the corresponding value(s) of the loss modulus.

lossmod(m::RheoModel, frequency (single value or array))

lossmod(m::RheoModelClass, frequency (single value or array), parameters (array, named tupple or keyword parameters))

Examples:

lossmod(Maxwell, 1, k=1., η=1)

lossmod(Maxwell, [1,2,3], [1,1])

When no time value is provided, lossmod returns the loss modulus function itself.

lossmod(m::RheoModel)

lossmod(m::RheoModelClass, parameters (array, named tupple or keyword parameters))

Examples:

m = RheoModel(Maxwell, k=1., η=1)
Gpp = lossmod(m)
Gpp([0,1,2])

dynamicmod(m[, ω, params])

provide access to the complex dynamic modulus (G' + i G'') of a given model m.

• When a frequency value is provided (or an array of frequency values), the function returns the corresponding value(s) of the complex dynamic modulus.

  dynamicmod(m::RheoModel, frequency (single value or array))

  dynamicmod(m::RheoModelClass, frequency (single value or array), parameters (array, named tupple or keyword parameters))

Examples:

dynamicmod(Maxwell, 1, k=1., η=1)

dynamicmod(Maxwell, [1,2,3], [1,1])

• When no time value is provided, lossmod returns the complex dynamic modulus function itself.

  dynamicmod(m::RheoModel)

  dynamicmod(m::RheoModelClass, parameters (array, named tupple or keyword parameters))

Examples:

m = RheoModel(Maxwell, k=1., η=1)
Gd = dynamicmod(m)
Gd([0,1,2])

Note: use abs() and angle() to get the magnitude and phase of the complex modulus.

resample(d::RheoTimeData [, t, dt, scale )

Resample the data using 1D spline extrapolation (using the Dierckx.jl package).

Arguments

• d: data as a RheoTimeData struct containing time with stress and/or strain. Without additional parameters, the data is resampled to provide a uniform sampling at constant number of timepoints.
• t: an array or range that determines the timepoints where the data will be provided.
• dt: if the array t is not provided, the parameter dt will set the timestep for a uniform resampling of the data.
• scale: instead of specifying particular time points or timestep, an overall multiplicator on the sampling rate can be provided. This could down-sample (scale<1) or upsample (scale>1). If timesteps are non uniform, it would interpolate values accordingly.

Examples

Assuming d is a RheoTimeData data set:

• resample(d) keeps the number of sampling points the same but interpolates to set a uniform time step.
• resample(d, t=-1:0.1:10) resamples by interpolation to generate a new dataset with time points given by the range t.
• resample(d, dt=0.1) resamples by interpolation to generate a new dataset with uniform time step dt.
• resample(d, scale=2) resamples by multiplying the sampling rate by 2.

indexweight(self::RheoTimeData; elperiods::Vector{K}, time_boundaries::Union{Nothing, Vector{T}} = nothing, includelast=true) where {K<:Integer,T<:Real}

This function returns array indices (i.e. an array of integers) which can be sent to the modelfit, modelstepfit or modeldiffeqfit functions to provide a weighted fitting whilst maintaining constant sample-rate.

Note that time_boundaries must have one more entry than elperiods so that all sections of weighting are fully defined by beginning and end points.

indexweight can underweight indices or overweight them. If elperiods in a given boundary is negative, every abs(n) index will be used, where n is the elperiod corresponding to a given boundary. If n is positive, then indicies will be duplicated n times such that they are given a higher weighting during the fitting procedure. If number of elements per period (elperiods) is 1 or -1 it returns the original indicies for that boundary, whilst 0 is not accepted as a valid argument for elperiods.

The last element may or may not be included. By default the last element is forced to be included but this can be negated by providing the keyword argument includelast=false.

cutting(self::RheoTimeData, time_on::Real, time_off::Real)

Remove the data outside a specified time interval.

By specifing a time interval (time_on, time_off), a new RheoTimeData is returned without the data lying outside time interval.

smooth(self::RheoTimeData, τ::Real; pad::String="reflect")

Smooth data using a Gaussian Kernel to time scale τ (approximately half power).

Smooths both σ and ϵ. Sampling frequency must be constant as it is based on FFT convolution. Essentially a low pass filter with frequencies of 1/τ being cut to approximately half power. For other pad types available see ImageFiltering documentation. As of doc writing, pad options are: "replicate" (repeat edge values to infinity), "circular" (image edges "wrap around"), "symmetric" (the image reflects relative to a position between pixels), "reflect" (the image reflects relative to the edge itself).

onlytime(d::RheoTimeData)

Return a RheoTimeData object with only the timeline of the parameter d.

onlystrain(d::RheoTimeData)

Return a RheoTimeData object with only the time and strain data of the parameter d.

onlystress(d::RheoTimeData)

Return a RheoTimeData object with only the time and stress data of the parameter d.

onlyfreq(d::RheoFreqData)

Return a RheoFreqData object with only the frequency data of the parameter d.

extract(self::Union{RheoTimeData,RheoFreqData}, type::Union{TimeDataType,FreqDataType,Integer})

Extract specific fields form RheoTimeData or RheoFreqData.

Deprecated - prefer to use the functions onlytime, onlystrain, onlystress, and onlyfreq.

Extract can copy one or more fields from a given RheoXData variable into a new RheoXData one. The fields that are copied are identified by the specified type of data. If self is a RheoTimeData, the type that can be extracted is time_only (or 0), stress_only (or 1), strain_only (or 2). Note that strain_and_stress (or 3) is not allowed. If self is a RheoFreqData, the type that can be extracted is freq_only (or 0).

modelfit(data::RheoTimeData, model::RheoModelClass, modloading::Symbol; p0::Union{NamedTuple,Nothing} = nothing, lo::Union{NamedTuple,Nothing} = nothing, hi::Union{NamedTuple,Nothing} = nothing, verbose::Bool = false, rel_tol_x = 1e-4, diff_method="BD", weights::Union{Vector{Integer},Nothing}=nothing)

Fit RheologyData struct to model and return a fitted model as a RheologyModel object. For the fitting process RHEOS relies on the optimistion package NLopt. By default, RHEOS makes use of a local derivative free algorithm, specifically the Tom Rowan's "Subplex" It is possible to specify which algorithm NLopt should use with the keyword parameter optmethod, by providing the relevant symbols as defined by NLopt.jl. Suitable options include :LN_SBPLX (default), :LN_COBYLA, :LN_BOBYQA for local derivative free optimisation. Global optimisation methods are also available, but require all parameters to have lower and upper bounds set. More information about these algorithms is available on the NLopt website.

Arguments

• data: RheoTimeData struct containing all data
• model: RheoModelClass containing moduli functions and named tuple parameters
• modloading: strain_imposed or 1, stress_imposed or 2
• p0: Initial parameters to use in fit (uses 0.5 for all parameters if not defined), provided as a named tuple
• lo: Lower bounds for parameters, provided as a named tuple
• hi: Upper bounds for parameters, provided as a named tuple
• verbose: If true, prints parameters on each optimisation iteration
• rel_tol_x: Relative tolerance of optimization as a function of input parameter values, see NLOpt docs for more details
• rel_tol_f: If given, sets a criterion based directly on changes of the function value
• diff_method: Set finite difference formula to use for derivative, currently "BD" or "CD"
• weights: Vector of indices weighted according to importance, can be generated by indexweight function
• optmethod: optimisation algorithm used by NLOpt (passed as symbol or string)
• opttimeout: allows user to set a wall clock timeout on optimisation, used to halt a failing optimisation and return safely
• optmaxeval: allows user to set a maximum number of evaluations during optimisation, used when repeatability is required

modelpredict(data::RheoTimeData, model::RheoModel; diff_method="BD")

Given an incomplete data set (only either stress or strain missing) and model with values substituted into parameters (RheoModel), return a new dataset based on the model. If data is type of stress_only, then the creep modulus is used; if data type is strain_only, the relaxation modulus is used. A complete RheoTimeData of type strain_and_stress is returned. diff_method sets finite difference for calculating the derivative used in the hereditary integral and can be either backwards difference ("BD") or central difference ("CD").

modelpredict(data::RheoTimeData, model::RheoModelClass; diff_method="BD", kwargs...)

Variation of modelpredict that takes a RheoModelClass and parameter values rather than an already created model. This speeds up the analysis when a large number of different parameter values need to be screened, as only the relevant modulus function is created for the purpose of model prediction.

modelstepfit(data::RheoTimeData, model::RheoModelClass, modloading::Union{LoadingType,Integer}; step=nothing, p0::Union{NamedTuple,Nothing} = nothing, lo::Union{NamedTuple,Nothing} = nothing, hi::Union{NamedTuple,Nothing} = nothing, verbose::Bool = false, rel_tol_x = 1e-4, weights::Union{Vector{Integer},Nothing} = nothing)

Same as modelfit except assumes a step loading. If this assumption is appropriate for the data then fitting can be sped up greatly by use of this function. If modloading is strain_imposed, relaxation modulus is used, then the element in the middle of the strain is assumed to be the amplitude of the step. If modloading is stress_imposed, the creep modulus is used, then the middle element of the stress is assumed to be the amplitude of the step. Alternatively, it is possible to define the value of the step by defining the optional step parameter.

Arguments

• data: RheoTimeData struct containing all data
• model: RheoModelClass containing moduli and parameters tuples
• modloading: strain_imposed for relaxation modulus, stress_imposed for creep modulus
• step: Optional amplitude for step
• p0: Named tuple of initial parameters to use in fit (uses 0.5 for all parameters if none given)
• lo: Named tuple of lower bounds for parameters
• hi: Named tuple of upper bounds for parameters
• verbose: If true, prints parameters on each optimisation iteration
• rel_tol_x: Relative tolerance of optimization as a function of input parameter values, see NLOpt docs for more details
• rel_tol_f: If given, overrides the default optimisation stopping criterion and sets a criterion based directly on changes of the function value
• weights: Vector of indices weighted according to importance, can be generated by indexweight function
• opttimeout: allows user to set a wall clock timeout on optimisation, used to halt a failing optimisation and return safely
• optmaxeval: allows user to set a maximum number of evaluations during optimisation, used when repeatability is required

modelsteppredict(data::RheoTimeData, model::RheoModel; step_on::Real = 0.0)

Same as modelpredict but assumes a step loading with step starting at step_on or closest actual value to that specified. If the loading data is variable, the magnitude in the middle of the array is used.

dynamicmodelfit(data::RheoFreqData, model::RheoModelClass; p0::Union{NamedTuple,Nothing} = nothing, lo::Union{NamedTuple,Nothing} = nothing, hi::Union{NamedTuple,Nothing} = nothing, verbose::Bool = false, rel_tol = 1e-4) where T<:Real

Fits model to the frequency/loss+storage moduli data.

All arguments are as described below. As this fitting procedure is fitting two functions simultaneously (the storage and loss moduli), if left untransformed the fit would tend to favour the modulus which is larger in magnitude and not fit the other modulus well. To avoid this, RHEOS offers a number of data transforms which can be used by changing weights argument.

Arguments

• data: RheoFreqData struct containing all data
• model: RheoModelClass containing moduli and symbols of parameters
• p0: Initial parameters to use in fit (uses 0.5 for all parameters if none given)
• lo: Lower bounds for parameters
• hi: Upper bounds for parameters
• verbose: If true, prints parameters on each optimisation iteration
• rel_tol_x: Relative tolerance of optimization for the vector of parameters, see NLOpt docs for more details
• rel_tol_f: Relative tolerance of optimization for the objective function, see NLOpt docs for more details
• weights: Weighting mode for storage and loss modulus ("none", "mean", "log", "local" or manually specified)

dynamicmodelpredict(data::RheoFreqData, model::RheoModel)

Given dynamic rheology data with only frequency and model where parameters have been substituted. Returns another RheoFreqData instance with the predicted Gp and Gpp based on the frequencies and model given as arguments.

timeline(r)

Generate RheoTimeData struct with only the time data based on the range provided.

Example:

timeline(0:0.1:10) returns a RheoTimeData with only time data, with the following series: [0. 0.1 0.2 ... 9.9 10].

timeline(;t_start::Real=0., t_end::Real, step::Real=(t_end - t_start)/250.)

Generate RheoTimeData struct with only the time data based on the keywords provided.

Arguments

• t_start: Starting time, typically 0
• t_end: End time
• step: Time between sample. Default set in order to provide ≈ 250 time points.

strainfunction(data::RheoTimeData, f::T) where T<:Function
strainfunction(f::T, data::RheoTimeData) where T<:Function

Returns a new RheoTimeData with strain values calculated by applying the function f to the time data of the parameter data.

Normally used with a RheoTimeData generated using the timeline function.

stressfunction(data::RheoTimeData, f::T) where T<:Function
stressfunction(f::T, data::RheoTimeData) where T<:Function

Returns a new RheoTimeData with stress values calculated by applying the function f to the time data of the parameter data.

Normally used with a RheoTimeData generated using the timeline function.

hstep(t; offset=0., amp=1.)

Step generation function for use with stressfunction or strainfunction. offset keyword arguent determines start of step. amp argument determines amplitude (height) of step.

ramp(t; offset=0., gradient=1.)

Ramp signal generation function for use with stressfunction or strainfunction. offset keyword argument determines start of ramp. gradient argument determines the linear gradient of the ramp.

stairs(t; offset=0., amp=1., width=1.)

Stairs signal generation function for use with stressfunction or strainfunction. Equivalent to additional steps being added every width seconds. offset keyword argument determines start of stairs signal. amp argument determines the height of each additional step.

square(t; offset=0., amp=1., period=1., width=0.5*period)

Square signal generation function for use with stressfunction or strainfunction. offset keyword argument determines start of square signal. amp argument determines the height of each square pulse. period determines the period of one off/on section of the square wave signal. width determines the width of each square pulse.

sawtooth(t; offset=0., amp=1., period=1.)

Sawtooth signal generation function for use with stressfunction or strainfunction. offset keyword argument determines start of sawtooth signal. amp argument determines the height of each sawtooth pulse. period determines the period of the sawtooth wave signal.

triangle(t; offset=0., amp=1., period=1.)

Triangle signal generation function for use with stressfunction or strainfunction. offset keyword argument determines start of triangle signal. amp argument determines the height of each triangle pulse. period determines the period of the triangle wave signal. width determines the width of the triangles.

frequencyspec(r::R; logscale=true)

Generate RheoFreqData struct with only the frequency data distributed on a linear or log scale.

Arguments

• r: range, e.g. 1:0.1:100
• logscale: if true, set the range in logscale, e.g. -2:0.1:20 –> 10 values per decade between 10^-2 and 10^2

frequencyspec(;ω_start::Real, ω_end::Real, logstep::Real= 0.05)

Generate RheoFreqData struct with only the frequency data distributed on a log scale.

Arguments

• ω_start: min frequency
• ω_end: max frequency
• logstep: step between frequencies in log scale, e.g. 0.1 –> 10 values per decade.

importcsv(filepath::String; delimiter=',', header=false, comment = "Imported from csv file", savelog = true, kwargs...)

Load data from a CSV file (two/three columns, comma separated by default but delimiter can be specified in the delimiter keyword argument).

The function can be used to construct either a RheoTimeData instance or a RheoFreqData instance, depending on the parameters provided or column names;the function detects whether time or frequency has been included and proceeds accordingly. For oscillatory data, all three columns (Gp, Gpp, Frequency) must be provided. For regular viscoelastic data only time, or time-stress, or time-strain or time-stress-strain data can be provided.

Column can be specified in the csv file by providing their values or header name (case insensitive) as keyword parameters.

importcsv("filename.csv", time=1, strain=2, stress=3) loads a RheoTimeData from a csv file with time in the first column, strain in the second, and stress in the third.

importcsv("filename.csv", omega="Frequency", Gp="Storage", Gpp="Loss") would detect the column numbers by reading the headers on the csv file.

If no information is provided, it would try to detect columns from header names, expecting standard names. Some of the recognised keywords are time, stress, strain, frequency, storage modulus, loss modulus.

If the csv file contains headers, but it is prefered to indicate columns by their numbers rather than header strings, the keyword header must be set to true.

importcsv(filepath::String, interface::Interface; delimiter = ',', header = false, comment = "Imported from csv file", savelog = true, kwargs...)

Import function for raw data to be transformed to stress and strain using an Interface. Column numbers in the csv containging the force/displacement data need to be indicated as keyword arguments using the corresponding symbols in the interface..

Examples

julia> importcsv("myfile.csv", AFM(2e-6), t=1, d=2, f=3)

exportcsv(self::Union{RheoTimeData, RheoFreqData}, filedir::String; delimiter=',', colorder=nothing)

Export RheoTimeData or RheoFreqData type to csv format. May be useful for plotting/analysis in other software. By default, full time data will be exported with columns ordered as (t, σ, ϵ). Partial time data will be ordered as either (t, σ) or (t, ϵ). Full frequency data will be ordered as (ω, Gp, Gpp). The order of columns can be customised by passing a NamedTuple to the colorder arguments. For example (σ = 1, t = 3, ϵ = 2) would export the columns in the order (σ, ϵ, t). As with importcsv, the delimiter can be set by keyword argument.