Invariant Models

Fourier_Grid(Phase_Dimension::Integer)

Creates a uniform grid on the $[0, 2\pi)$ interval.

Fourier_Interpolate(grid, theta::Number)

Evaluates the set of Dirichlet kernels specific to the uniform grid at point theta. The result is a vector.

Fourier_Interpolate(grid, theta::AbstractArray{T,1}) where {T}

Evaluates the set of Dirichlet kernels specific to the uniform grid at all points in theta. The result is a matrix, where each column corresponds to a value in theta.

Rigid_Rotation_Matrix!(Alpha_Matrix, Grid, Omega_ODE::Number, t::Number)

Creates the fundamental solution matrix for the rigid rotation on the circle in the space of the uniform Grid on the circle. The angular speed of the rotation is Omega_ODE and the result is written into Alpha_Matrix. The indepedent variabe is t.

Rigid_Rotation_Generator(Grid, Omega_ODE::Number)

This is the infinitesimal generator of the rigid rotation with Omega_ODE angular speed.

Chebyshev_Grid(np::Integer)

Creates a Chebyshev grid with np grid points.

\[t_j = \cos\frac{(j-1) \pi }{n-1},\;\; j =1,\ldots,n\]

Chebyshev_Grid(np::Integer, a::T, b::T) where {T<:Number}

Creates a Chebyshev grid with np grid points within the interval $[a, b]$.

\[t_j = \frac{a+b}{2} + \frac{a-b}{2} \cos\frac{(j-1) \pi }{n-1},\;\; j =1,\ldots,n\]

Barycentric_Interpolation_Matrix(t::AbstractVector, ti::AbstractVector)

Creates a matrix that performs a polynomial interpolation from grid t to grid ti.

Barycentric_Interpolation_Matrix(order::Integer, mesh::Vector, ti::AbstractVector)

Creates a matrix that performs a polynomial interpolation from a mesh, where each interval has order number of Chebyshev points. The target points are in grid.

Delay_Embed(Signals, Phases; delay = 1, skip = 1, max_length = typemax(Int))

Creates a delay embedding of Signals while limits trajectory length to max_length. The delay is delay long and only every skipth point along the trajectory is put into the delay embedded data. Phases are simply copied over to the output while making sure that signal lengths and phase length are the same, limited by max_length.

The return values Delay_Signals, Delay_Phases are matrices of appropriate sizes.

Chop_And_Stitch(Signals, Phases; maxlen = 1000)

Chops up Signals and Phases into chunks of maximum maxlen chuncks. Then concatenates the result into the arrays Index_List, Data, Encoded_Phase. The list Index_List tells, where each chunk starts and ends within the arrays Data and Encoded_Phase.

Estimate_Linear_Model(
    Index_List,
    Data,
    Encoded_Phase,
    Scaling;
    Iterations = 0,
    Order = 1,
)

Given the data Index_List, Data, Encoded_Phase this function estimates a linear model, a steady state and a model of forcing.

The output is Steady_State, BB_Linear, SH. Steady_State is the steady state of the system, BB_Linear is the estimated linear model and SH is the unitary transformation representing forcing.

When fitting the linear model Scaling attaches an importance to each data point. Iterations allows us to take into account the data as trajectories and use multi-step optimisation to find BB_Linear. A nonlinear model can also be fitted by making Order $> 1$. When a nonlinear model is identified, its steady state is found by Newton's method and its Jacobian is calculated at the steady state, which is then returned as the linear model BB_Linear.

Filter_Linear_Model(BB, Grid, order)

Assuming a uniform Fourier grid Grid, this function returns a truncated Fourier series of the linear model BB. This removes inaccurate higher frequency components of the approximate linear model before decomposing it into invariant vector bundles.

Create_Linear_Decomposition(
    BB_Filtered,
    SH;
    Time_Step = 1.0,
    Reduce = false,
    Align = true,
    By_Eigen = false,
)

Creates an invariant vector bundle decomposition of the linear system represented by BB_Filtered and the forcing dynamics SH. If Time_Step is specified, the fucntion also prints the estimated natural frequencies and damping ratios. The decomposition outputs vector bundles with orthonormal bases. Therefore the reduced model will be block-diagonal (with at most $2\times 2$ blocks), but not autonomous. If Reduce == true the system will be reduced to an autonomous form and the vector bundles will only be orthogonal in a weaker sense, averaged over the phase space of the forcing dyamics.

The output is a named tuple

(
    Unreduced_Model,
    Data_Encoder,
    Data_Decoder,
    Bundles,
    Reduced_Model,
    Reduced_Encoder,
    Reduced_Decoder,
)

where

• Unreduced_Model is the block diagonal, but non-autonomous model.
• Data_Encoder is the transformation that brings the data into the block-diagonal form.
• Data_Decoder is the transformation that brings the model back into the coordinate system of the data.
• Bundles is a list of ranges that point out which entries of the Unreduced_Model are a vector bundle.
• Reduced_Model is the autonomous reduced model, if Reduce == true, otherwise same as Unreduced_Model.
• Reduced_Encoder brings Unreduced_Model into Reduced_Model if Reduce == true otherwise identity.
• Reduced_Decoder brings Reduced_Model back into Unreduced_Model if Reduce == true otherwise identity.

The parameter By_Eigen is true if the calculation is carried out by eigenvalue decomposition of the transport operator. Otherwise a specially designed Hessenberg transformation and subsequent QR iteration is carried out on the vector bundles. This latter method

Select_Bundles_By_Energy(
    Index_List,
    Data,
    Encoded_Phase,
    Steady_State,
    SH,
    Decomp;
    How_Many,
    Ignore_Real = true,
)

Takes the named tuple produced by Create_Linear_Decomposition and selects the most energetic How_Many vector bundles of the data. Then produces a new named touple as in Create_Linear_Decomposition, that only contains these most energetic vector bundles. The input arguments are

• Index_List, Data, Encoded_Phase are the training data in the standard form.
• Steady_State is the steady state of the system estimated by Estimate_Linear_Model.
• SH is the forcing dynamics as produced by Estimate_Linear_Model.
• Decomp is the named tuple produced by Create_Linear_Decomposition.
• Ignore_Real if true the method only returns two dimensional vector bundles. This is helpful when the data includes slowly varying DC shift with high energy that would be pick by the method otherwise.

Decompose_Data(Index_List, Data, Encoded_Phase, Steady_State, SH, Data_Encoder)

Creates a decomposed and projected data set from the input Index_List, Data, Encoded_Phase. The Steady_State and SH are produced by Estimate_Linear_Model and Data_Encoder id produced by either Select_Bundles_By_Energy or Create_Linear_Decomposition directly.

Decomposed_Data_Scaling(Data_Decomp, Bundles)

Creates a scaling tensor which, when applied to Data_Decomp makes each vector bundle have the same maximum amplitude, while also making the whole data set fit inside the unit ball.

Generate_From_ODE(
    Vectorfield!,
    Forcing_Map!,
    Alpha_Map!,
    Parameters,
    Time_Step,
    IC_x,
    IC_Force,
    IC_Alpha,
    Trajectory_Lengths,
)

Generates a data set from am ordinary differential equation (ODE). The ODE is defined by the three functions Vectorfield!, Forcing_Map! and Alpha_Map!.

• Time_Step is the sampling time interval of the soluation
• IC_x each column contains an initial condition in the state space
• IC_Force this is a storage space and will be overwritten with the actual value of the forcing state Alpha
• IC_Alpha each column contains an initial condition of the forcing state
• Trajectory_Lengths a vector of trajectory lengths

The return values are List_Of_Trajectories, List_Of_Phases, which can be further processed by identifying a linear model Estimate_Linear_Model.

An example of the ODE is

function Vectorfield!(dx, x, u, Parameters)
    ... dx is the dx/dt
    ... x is the state variable vector
    ... u is the time varying input or forcing vector
    ... Parameters is a data structure that is passed around all function
        and contains all auxilliary information necessary to calculate dx
    ...
    return x
end

function `Forcing_Map!`(u, Alpha, Parameters)
    ... This function produces the forcing vector 'u'
    ... The state variable of the forcing is `Alpha`
    ... Parameters is a data structure that is passed around all function
    ... The forcing depends on the state variable of the forcing `Alpha`
    ... In this case the forcing is just a linear combination of `Alpha`
    u[1:2] .= Parameters.Weights * Alpha
    return u
end

function Alpha_Map!(x, Parameters, t)
    ... Returns a matrix, which is the fundamental solution of the forcing dynamics
    ... 'x' is the fundamental solution
    ... Parameters is a data structure that is passed around all function
    ... `t` is the independent time variable
    return Rigid_Rotation_Matrix!(x, Parameters.Forcing_Grid, Parameters.Omega, t)
end

@enum Encoder_Linear_Type begin
    Encoder_Fixed = 0
    Encoder_Array_Stiefel = 1
    Encoder_Mean_Stiefel = 2
    Encoder_Stiefel_Oblique = 3
    Encoder_Orthogonal = 4
end

Enumeration to describe the linear part of the Encoder.

• Encoder_Fixed the encoder is not optimised, it is left fixed at its initial state
• Encoder_Array_Stiefel the encoder is a pointwise orthogonal set of matrices
• Encoder_Mean_Stiefel the encoder is orthogonal in an average sense over all possible forcing
• Encoder_Stiefel_Oblique the encoder consist of unit vectors for all points of forcing (not orthogonal)
• Encoder_Orthogonal the encoder is orthogonal to all linear parts of the other foliations and this orthogonality is periodically updated with the other foliations

@enum Encoder_Nonlinear_Type begin
    Encoder_Dense_Full = 0
    Encoder_Dense_Latent_Linear = 1
    Encoder_Dense_Local = 2
    Encoder_Compressed_Full = 16
    Encoder_Compressed_Latent_Linear = 17
    Encoder_Compressed_Local = 18
end

Enumeration to describe the nonlinear part of the Encoder

• Encoder_Dense_Full the encoder is a dense polynomial without any constraints
• Encoder_Dense_Latent_Linear the encoder is a dense polynomial, but it is linear for the latent variables
• Encoder_Dense_Local the encoder is a dense polynomial, but it is locally defined about an invariant manifold
• Encoder_Compressed_Full the encoder is a compressed polynomial without any constraints
• Encoder_Compressed_Latent_Linear the encoder is a compressed polynomial, but it is linear for the latent variables
• Encoder_Compressed_Local the encoder is a compressed polynomial, but it is locally defined about an invariant manifold

MultiStep_Model(State_Dimension, Skew_Dimension, Start_Order, End_Order, Trajectories)

Create a polynomial model representation.

• State_Dimension dimensionality of the state space
• Skew_Dimension dimensionality of the forcin space
• Start_Order the smallest order monomial to include
• End_Order the greatest order monomial to include
• Trajectories number of trajectories to be represented

The model includes an identified initial condition for each fitted trajectory, which is different from the first point of the trajectory.

From_Data!(M::MultiStep_Model, X, Index_List, Data, Encoded_Phase, Scaling; Linear=false)

Creates a polynomial model from data given by Index_List, Data, Encoded_Phase. The model is created using linear least squares and therefore not optimised. This is to provide an initial condition for optimisation later on.

• M, X the model representation
• Index_List, Data and Encoded_Phase input data
• Scaling a scaling factor to represent the importance of each data point
• Linear if true all nonlinear terms are zeroed

Evaluate(M::MultiStep_Model, X, Index_List, Data, Encoded_Phase)

Applies the polynomial representation of the model M, X to the data Index_List, Data, Encoded_Phase as if each data point was an initial condition.

Slice(MTF::Multi_Foliation{M,State_Dimension,Skew_Dimension}, XTF, Encoded_Slice) where {M,State_Dimension,Skew_Dimension}

In case the system is parameter dependent, this function creates an autonomous slice when the encoded parameter is Encoded_Slice.

Model_From_ODE(
    Vectorfield!,
    Forcing_Map!,
    Alpha_Map!,
    IC_Force,
    Parameters,
    dt,
    Time_Step;
    State_Dimension,
    Skew_Dimension,
    Start_Order,
    End_Order,
    Steady_State::Bool = true,
    Iterations = 100,
)

Creates a discrete-time model from the vector field Vectorfield!, Forcing_Map! and Alpha_Map!. The definition is the same as in Generate_From_ODE. The routine first calculates a steady state of the system straight from the ODE. Then it create a polynomial map about the steady state. The resulting map has its steady state at the origin.

• dt time step of the ODE solver
• Time_Step integration time of the ODE. One iteration of the resulting map is the same as solveing the ODE for Time_Step time.
• State_Dimension state space dimension
• Skew_Dimension forcing space dimension
• Start_Order starting order of the resulting map
• End_Order highest order monomial in the resulting map
• Iterations how many Newto iteration to take when solving for the steady state.

Model_From_Function_Alpha(
    Vectorfield!,
    Alpha_Generator,
    Parameters;
    State_Dimension,
    Start_Order,
    End_Order
)

Create a polynomial vector field by Taylor expanding the ODE given by Vectorfield! and Alpha_Generator.

It uses the same definition a a vector field as Generate_From_ODE. The difference is that Alpha_Generator is the infinitesimal generator matrix of the forcing dynamics.

Start_Order and End_Order set the representing polynomial orders.

@enum Scaling_Type begin
    No_Scaling = 0
    Linear_Scaling = 1
    Quadratic_Scaling = 2
end

Describes how to scale the loss function as a function of the distance from the steady state.

Make_Similar(
    MTF::Multi_Foliation{M,State_Dimension,Skew_Dimension},
    XTF,
    New_Trajectories::Integer,
) where {M,State_Dimension,Skew_Dimension}

Creates a new Multi_Foliation except that it will now have space for New_Trajectories initial conditions for the conjugate dynamics. This is used to create a model to evaluate testing data that has different number of trajectories than the training data.

Multi_Foliation_Problem(
    Index_List,
    Data_Decomposed,
    Encoded_Phase;
    Selection::NTuple{M, Vector{Int}},
    Model_Orders::NTuple{M, Int},
    Encoder_Orders::NTuple{M, Int},
    Unreduced_Model,
    Reduced_Model,
    Reduced_Encoder,
    SH,
    Initial_Iterations = 32,
    Scaling_Parameter = 2^(-4),
    Initial_Scaling_Parameter = 2^(-4),
    Scaling_Order = Linear_Scaling,
    node_ratio = 0.8,
    leaf_ratio = 0.8,
    max_rank = 48,
    Linear_Type::NTuple{M, Encoder_Linear_Type} = ntuple(i -> Encoder_Array_Stiefel, M),
    Nonlinear_Type::NTuple{M, Encoder_Nonlinear_Type} = ntuple(i -> Encoder_Compressed_Latent_Linear, M),
    Name = "MTF-output",
    Time_Step = 1.0,
) where {M}

Creates an object with multiple foliations that can be fitted to the data.

• Index_List, Data_Decomposed and Encoded_Phase The training data approximately in the cooredinates of the invariant vector bundles of the linear part of the system about the steady state. This transformation can be achieved by Decompose_Data and the decomposition can be obtained by Create_Linear_Decomposition, which in turn is obtained by an initial linear approximation of the model using Estimate_Linear_Model.
• Selection sets the vector bundles to be included in the calculated foliations.
• Model_Orders the polynomial orders of the conjugate maps for each foliation
• Encoder_Orders the polynomial orders of the conjugate maps for each foliation
• Unreduced_Model approximate linear model in the coordinate system of the data
• Reduced_Model approximate (autonomous) linear model in the coordinate system of Reduced_Encoder
• Reduced_Encoder a linear encoder that reduces the approximate linear map Unreduced_Model to an autonomous map. It can also be an identity, in which case the Reduced_Model and the Unreduced_Model are the same
• SH The forcing map, identified by Estimate_Linear_Model
• Initial_Iterations how many optimisation steps to take to refine the supplied linear model to the encoded data
• Scaling_Parameter the parameter the specifies data scaling
• Initial_Scaling_Parameter the parameter the specifies data scaling at the initial refinement of the model. Choosing it too small might result in diverging calculations.
• Scaling_Order whether to assign different important to various data points. This is must be one element of Scaling_Type
• node_ratio when calculating the rank of a component in the compressed tensor representation, by what ratio should we reduced the rank of the connecting parent node.
• leaf_ratio by how much are we allowed to reduce the rank of a leaf node from the dimeneionality of the tensor
• max_rank the maximum rank of any node in the compressed tensor representation
• Linear_Type this is a tuple that contains what restriction should apply to the linear part of the encoder. The values are taken from Encoder_Linear_Type
• Nonlinear_Type this is a tuple that contains what restriction should apply to the nonlinear part of the encoder. The values are taken from Encoder_Nonlinear_Type
• Name this string variabel is used for the name of the data file wher the foliation is periodically save to.
• Time_Step the sampling time step of the supplied data. This is used only to display frequency information during calulation, otherwise has no effect.

Multi_Foliation_Test_Problem(
    MTFP::Multi_Foliation_Problem{M,State_Dimension,Skew_Dimension},
    Index_List,
    Data_Decomposed,
    Encoded_Phase;
    Initial_Scaling_Parameter = 2^(-4),
) where {M,State_Dimension,Skew_Dimension}

This creates a test problem with test data included. The test data in Index_List, Data_Decomposed and Encoded_Phase. MTFP is a Multi_Foliation_Problem. Initial_Scaling_Parameter has the same meaning as in Multi_Foliation_Problem but applied to the testing data.

Optimise!(
    MTFP::Multi_Foliation_Problem{M,State_Dimension,Skew_Dimension},
    MTFP_Test::Union{Nothing,Multi_Foliation_Problem{M,State_Dimension,Skew_Dimension}} = nothing;
    Model_Iterations = 16,
    Encoder_Iterations = 8,
    Steps = 128,
    Gradient_Ratio = 2^(-7),
    Gradient_Stop = 2^(-29),
    Picks = [Complete_Component_Index(MTFP.XTF.x[k].x[2], (1,)) for k = 1:M],
) where {M,State_Dimension,Skew_Dimension}

Fits the set of foliations defined in MTFP to the given data.

• MTFP a Multi_Foliation_Problem
• MTFP_Test a Multi_Foliation_Test_Problem. The parameters of MTFP_Test are regularly synchronised with MTFP, except the initial condition of the latent model, which are fitted from the testing trajectories.
• Model_Iterations maximum number of optimisation steps taken when the conjugate dynamics is fitted to latent data. The optimisation is a version of the Levenberg-Marquardt method.
• Encoder_Iterations maximum number of optimisation steps for any component of the encoder. The optimisation technique is a manifold Newton trust region method.
• Steps the number of optimisation cycles for each foliation.
• Gradient_Ratio Optimisation of a component stops when the norm of the gradient has reduced by this factor
• Gradient_Stop Optimisation of a component stops when the norm of the gradient has reached this value
• Picks Used for testing the code, leave as is.

Find_DATA_Manifold(MTF::Multi_Foliation{M,State_Dimension,Skew_Dimension}, XTF, SH, Index;
    Radial_Order, Radial_Intervals, Radius,
    Phase_Dimension, Transformation,
    abstol=1e-9, reltol=1e-9, maxiters=12, initial_maxiters=200
) where {M,State_Dimension,Skew_Dimension}

Calculates a two-dimensional invariant manifold from the set of invariant foliations MTF, XTF. The calulation is for the invariant foliation selected by Index. SH is the forcing map. The rest of the function arguments are the same as in Find_MAP_Manifold

Extract_Manifold_Embedding(
    MTF::Multi_Foliation{M,State_Dimension,Skew_Dimension},
    XTF,
    Index,
    Data_Decomp,
    Encoded_Phase;
    Radial_Order,
    Radial_Intervals,
    Radius,
    Phase_Dimension,
    Output_Transformation = [],
    Output_Inverse_Transformation = [],
    Output_Scale,
    abstol = 1e-9,
    reltol = 1e-9,
    maxiters = 24,
    initial_maxiters = 200,
)

Extracts the invariant manifold from a set of invariant foliations MTF, XTF. The parametrisation of the foliation is the same as the identofied conjugate map. Therefore it is not directly useable to obtain backbone curves. The result is primarily used to find out the physical amplitude of an encoded data point that is mapped back onto the invariant manifold.

The input arguments are

• MTF, XTF represent the set of invariant foliations previously fitted to data
• Index chooses the invariant foliation for which we calculate the invariant manifold
• Radial_Order order of the Chebyshev in the radial direction
• Radial_Intervals number of polynomials in the radial direction
• Radius the maximum radius to calculate the invariant manifold for
• Phase_Dimension the number of Fourier collocation points to use in the angular direction
• Output_Transformation same as Data_Encoder produced by Create_Linear_Decomposition.
• Output_Inverse_Transformation same as Data_Decoder produced by Create_Linear_Decomposition. Note that only one of Output_Transformation or Output_Inverse_Transformation need to be specified. If Output_Inverse_Transformation is specified, it takes precedence.
• Output_Scale same as Data_Scale produced by Decomposed_Data_Scaling
• abstol = 1e-9 absolute tolerance when solving the invariance equation
• reltol = 1e-9 relative tolerance when solving the invariance equation
• maxiters = 12 number of solution steps when calculating each segment of the manifold
• initial_maxiters the maximum iteration when calculating the segment containing the steady state. About the steady state the manifold is non-hyperbolic and therefore numerically challenging to calculate.

Data_Result(
PM::Polar_Manifold{
    State_Dimension,
    Latent_Dimension,
    Radial_Order,
    Radial_Dimension,
    Phase_Dimension,
    Skew_Dimension,
},
PX,
MIP,
XIP,
MTF::Multi_Foliation,
XTF,
Index,
Index_List,
Data,
Encoded_Phase;
Time_Step = 1.0,
Transformation = PM.Transformation,
Slice_Transformation = Transformation,
Hz = false,
Damping_By_Derivative::Bool = true,
Model_IC = false,

) where { StateDimension, LatentDimension, RadialOrder, RadialDimension, PhaseDimension, SkewDimension, }

Plots the instantaneous frequency and damping curves for the invariant foliation at Index.

• PM, PX the invariant manifold calculated by Find_DATA_Manifold
• MIP, XIP the manifold embedding calculated by Extract_Manifold_Embedding
• MTF, XTF the set of invariant foliations
• Index which invariant foliation is it calculated for
• Index_List, Data, Encoded_Phase the training data
• Time_Step sampling time-step of data for calulating frequencies
• Transformation the transformation the brings back the data to the physical coordinate
• Slice_Transformation the transformation, in case PM, PX are calculated from a fixed parameters slice of the identified foliation. If not a slice, should be the same as Transformation.
• Hz if true frequency is displayed in Hz, otherwise it is rad/s.
• Damping_By_Derivative if true a truely instantaneous damping ratio is displayed. If false the damping ratio commonly (and mistakenly) used in the literature is displayed
• Model_IC whether to re-calculate the initial conditions of trajectories stored in XTF

Data_Error(
PM::Polar_Manifold{
    State_Dimension,
    Latent_Dimension,
    Radial_Order,
    Radial_Dimension,
    Phase_Dimension,
    Skew_Dimension,
},
PX,
MIP,
XIP,
MTF::Multi_Foliation,
XTF,
Index,
Index_List,
Data,
Encoded_Phase;
Transformation,
Model_IC = false,
Iterations = 32,

) where { StateDimension, LatentDimension, RadialOrder, RadialDimension, PhaseDimension, SkewDimension, } )

Plots the training and testing errors as a function of vibration amplitude.

• PM, PX the invariant manifold calculated by Find_DATA_Manifold
• MIP, XIP the manifold embedding calculated by Extract_Manifold_Embedding
• MTF, XTF the set of invariant foliations
• Index which invariant foliation is it calculated for
• Index_List, Data, Encoded_Phase the training data
• Transformation the transformation the brings back the data to the physical coordinate
• Color line colour of the plot
• Model_IC whether to re-calculate the initial conditions of trajectories stored in XTF

Find_ODE_Manifold(
    MM::MultiStep_Model,
    MX,
    Generator,
    Select;
    Radial_Order,
    Radial_Intervals,
    Radius,
    Phase_Dimension,
    abstol = 1e-9,
    reltol = 1e-9,
    maxiters = 12,
    initial_maxiters = 200,
)

Calculates a two-dimensional invariant manifold from the ODE MM, MX. The result is stored as a piecewise Chebyshev polynomial in the radial direction Fourier collocation in the angular direction.

The input arguments are

• MM and MX represent the polynomial vector field
• Generator is the infinitesimal generator matrix of the forcing dynamics
• Select chooses along which vector bundle to calculate the invariant manifold
• Radial_Order order of the Chebyshev in the radial direction
• Radial_Intervals number of polynomials in the radial direction
• Radius the maximum radius to calculate the invariant manifold for
• Phase_Dimension the number of Fourier collocation points to use in the angular direction
• abstol = 1e-9 absolute tolerance when solving the invariance equation
• reltol = 1e-9 relative tolerance when solving the invariance equation
• maxiters = 12 number of solution steps when calculating each segment of the manifold
• initial_maxiters the maximum iteration when calculating the segment containing the steady state. About the steady state the manifold is non-hyperbolic and therefore numerically challenging to calculate.

Find_MAP_Manifold(
    MM::MultiStep_Model{State_Dimension,Skew_Dimension,Start_Order,End_Order,Trajectories},
    MX,
    Select;
    Radial_Order,
    Radial_Intervals,
    Radius,
    Phase_Dimension,
    abstol = 1e-9,
    reltol = 1e-9,
    maxiters = 12,
    initial_maxiters = 200,
) where {State_Dimension,Skew_Dimension,Start_Order,End_Order,Trajectories}

Calculates a two-dimensional invariant manifold from the map MM, MX. The result is stored as a piecewise Chebyshev polynomial in the radial direction Fourier collocation in the angular direction.

The input arguments are

• MM and MX are the discrete-time map
• Select chooses along which vector bundle to calculate the invariant manifold
• Radial_Order order of the Chebyshev in the radial direction
• Radial_Intervals number of polynomials in the radial direction
• Radius the maximum radius to calculate the invariant manifold for
• Phase_Dimension the number of Fourier collocation points to use in the angular direction
• abstol = 1e-9 absolute tolerance when solving the invariance equation
• reltol = 1e-9 relative tolerance when solving the invariance equation
• maxiters = 12 number of solution steps when calculating each segment of the manifold
• initial_maxiters the maximum iteration when calculating the segment containing the steady state. About the steady state the manifold is non-hyperbolic and therefore numerically challenging to calculate.

Model_Result(
    PM::Polar_Manifold,
    PX;
    Time_Step = 1.0,
    Hz = false,
    Damping_By_Derivative::Bool = true,
)

Calculates the instantaneous frequency and damping ratio for the invariant manifold directly calculated from an ODE or map model.

• PM, PX the invariant manifold calculated by Find_ODE_Manifold or Find_MAP_Manifold
• Time_Step sampling time-step of data for calulating frequencies
• Hz if true frequency is displayed in Hz, otherwise it is rad/s.
• Damping_By_Derivative if true a truely instantaneous damping ratio is displayed. If false the damping ratio commonly (and mistakenly) used in the literature is displayed

Create_Plot(; Amplitude = "Amplitude")

Creates a figure to display the results.

• Amplitude is a string that will be put on the vertical axes of the plot

Plot_Error_Curves!(
    fig, Error_Curves, Data_Max_Pre;
    Color = Makie.wong_colors()[2],
    Dense_Style = :solid,
    Max_Style = :dot,
    Mean_Style = :solid,
    Amplitude_Scale = 1,
)

• fig is the figure to plot
• Error_Curves produced by Data_Error
• Data_Max_Pre the maximum amplitude to consider
• Color line colour
• Dense_Style line style for density
• Max_Style line style for maximum error
• Mean_Style line style for mean error
• Amplitude_Scale a scaling factor for amplitudes. This can be use because the result is in different units.

Plot_Error_Trace(
    fig,
    Index,
    Train_Trace,
    Test_Trace = nothing;
    Train_Color = Makie.wong_colors()[1],
    Test_Color = Makie.wong_colors()[2],
)

Adds the training and testing errors to the figure fig for the foliation selected by Index. Train_Trace and Test_Trace are produced by Optimise!.

Annotate_Plot!(fig)

Perform the final annotation of the figure, so that it is ready for display.