API

BilliardV

A callable struct to represent a vector field with multiple hyper surfaces such that the flow jump when hits these hyper surfaces.

Fields

• f is the vector field, of type f(x,p,t), and its output is a SVector;
• hypers is tuple of hyper surfaces:(h1,h2,...), h1(x,p,t);
• rules is tuple of rules on hyper surfaces:(r1,r2,r3,...).

FlawPoint{N,T}

FlawPoint is a struct to record the points that don't satisfy the angle and distance request while the program has reached the minimum arc length.

Fields

• point flaw point in the process of continuation;
• α the angle recorded;
• d the distance recorded.

NSOneDManifold{F,S,N,T}

NSOneDManifold is a struct contains all the information of the non-smooth one-dimensional numerical manifold.

Fields

• prob the problem NSOneDManifoldProblem;
• data the numerical data that should be Vector{Vector{Vector{S}}}, where S is the interpolation curve (we use DataInterpolation in this package);
• flawpoints the flaw points generated during continuation.

NSOneDManifoldProblem{F,T}

NSOneDManifoldProblem is a struct to contain the main information for continuing the non-smooth one-dimensional manifold of the time-T-map of a non-smooth ODE.

Fields

• f the struct NSSetUp;
• para the parameters of the nonlinear map;
• amax the maximum angle between points when continuing the manifold;
• d the maximum distance between points when continuing the manifold;
• ϵ the max value of the following expression: $\max\{|H(x_0,T)|,H(x_1,T)\},$ where $H(x,t)$ is the hypersurface the manifold cross, $x_0$ and $x_1$ are points before and after the cross, $T$ is the end of the time-$T$-map (from 0 to $T$).
• dsmin the minimum arc length allowing; note that if in a continuation point, this value is achieved and the angle as well as the distance values are not achieved, then we will record this point as a FlawPoint.

Convenient consturctors are NSOneDManifoldProblem(f) and NSOneDManifoldProblem(f,para)

NSSetUp{T}

NSSetUp is a struct to contain all the information needed in continuing the manifold of non-smooth ODE.

Fields

• f the Non-smooth vector field, like PiecewiseV;
• timespan the time span of time-T-map;
• timetmap the time-t-map of non-smooth ODE, which maps a NSState and parameters of ODE to a NSState.

NSSolution{N,T<:Number}

The NSSolution is a struct to contain all information of the solution of a non-smooth ODE system.

Fields

• sol ODESolution solved by OrdinaryDiffEq;
• event_t the times when events happen;
• event_state the solution's state when events happen;
• event_at is a vector that contains integers indicating which event happen.

NSState{N,T<:Number} <: AbstractVector{T}

The struct NSState is to record the events data for a time-T-map.

Fields

• state the final state of the time-T-map;
• event_at is a integer vector that contains the history of the events happened.

The construction of NSState allows to interpolate vectors consisting of NSState. Currently, LinearInterpolation, CubicSpline, and QuadraticInterpolation in DataInterpolations.jl are supported.

NSVTwoDManifold{F,S,N,T}

NSVTwoDManifold is a struct contains all the information of the non-smooth two-dimensional numerical manifold of an autonomous vector field.

Fields

• prob the problem NSVTwoDManifoldProblem;
• data the numerical data that should be Vector{Vector{S}}, where S is the interpolation curve (we use DataInterpolation in this package);
• flawpoints the flaw points generated during continuation.

NSVTwoDManifoldProblem{F,T}

NSVTwoDManifoldProblemVTwoDManifoldProblem is a struct to contain the main information for continuing the two-dimensional manifold of an autonomous vector field.

Fields

• f the NSSetUp of a nonsmooth vector field;
• para the parameters of the time flow map;
• amax the maximum angle between points when continuing the manifold;
• d the maximum distance between points when continuing the manifold;
• ϵ the max value of the following expression: $\max\{|H(x_0,T)|,H(x_1,T)\},$ where $H(x,t)$ is the hypersurface of the manifold cross, $x_0$ and $x_1$ are points before and after the cross, $T$ is the end of the time-$T$-map (from 0 to $T$).
• dsmin the minimum arc length allowing; note that if in a continuation point, this value is achieved and the angle as well as the distance values are not achieved, then we will record this point as a FlawPoint.

Convenient consturctors are NSVTwoDManifoldProblem(f) and NSVTwoDManifoldProblem(f,para)

ODESolver{F1,F2,T}

A wrapper struct for solving ordinary differential equations (ODEs).

Fields

• f: Vector field function of the ODE system in the form f(x,p,t)
• timespan: Time interval for solving the ODE, of type Tuple{T,T}
• alg: The numerical algorithm used for solving the ODE
• abstol: Absolute tolerance for the numerical solver

OneDManifold{F,S,N,T}

OneDManifold is a struct contains all the information of the one-dimensional numerical manifold.

Fields

• prob the problem OneDManifoldProblem;
• data the numerical data that should be Vector{Vector{S}}, where S is the interpolation curve (we use DataInterpolation in this package);
• flawpoints the flaw points generated during continuation.

OneDManifoldProblem{F,T}

OneDManifoldProblem is a struct to contain the main information for continuing the one-dimensional manifold of a nonlinear map.

Fields

• f the nonlinear map, which should has the form f(x,p) and return a SVector;
• para the parameters of the nonlinear map;
• amax the maximum angle between points when continuing the manifold;
• d the maximum distance between points when continuing the manifold;
• dsmin the minimum arc length allowing; note that if in a continuation point, this value is achieved and the angle as well as the distance values are not achieved, then we will record this point as a FlawPoint.

Convenient consturctors are OneDManifoldProblem(f) and OneDManifoldProblem(f,para)

PiecewiseImpactV

A callable struct to represent a vector field with both piecewise non-smoothness and impacts.

• fs is a tuple of smooth vector fields in different regions.
• regions is a tuple of the region functions: (r1,r2,...), where r1(x,p,t) should return a Bool value to indicate that x is in this region or not.
• hypers is a tuple of the hyper surfaces separating the regions.
• rules is a tuple of rules on hyper surfaces:(r1,r2,r3,...). Note that for hypersurfaces that only switch between two vector fields, we can set r1=id.
• idxs is a vector of integer to indicate hypersurfaces with impact effects.
• n is a integer to switch between vector fields. Default to be zero.

PiecewiseV

A callable struct to represent a piecewise smooth vector field.

Fields

• fs is a tuple of smooth vector fields in different regions.
• regions is a tuple of the region functions: (r1,r2,...), where r1(x,p,t) should return a Bool value to indicate that x is in this region or not.
• hypers is a tuple of the hyper surfaces separating the regions.
• n is a integer to switch between vector fields. Default to be zero.

Example

using StaticArrays, InvariantManifolds
f1(x,p,t)=SA[x[2],-2x[1]]
f2(x,p,t)=SA[x[2],-x[1]]
dom1(x,p,t)=x[1]>0
dom2(x,p,t)=x[2]<0
hyper(x,p,t)=x[1]
PiecewiseV((f1,f2),(dom1,dom2),(hyper,))

The above codes generate a piecewise smooth vector field, which when x[1]>0 is f1, and when x[2]<0 is f2. The hyper surface separating these smooth vector fields is x[1]=0.

Saddle{N,T,S}

Saddle is a struct to contain the information of a saddle point needed in continuing the manifold of non-smooth ODE. For an ODE's saddle, this struct can be constructed by the function findsaddle.

Fields

• saddle the location of the saddle point;
• unstable_directions the unstable directions;
• unstable_eigen_values eigenvalues of the linearized map in the saddle at the unstable eigenvectors.

TwoDManifold{F,S,N,T}

TwoDManifold is a struct contains all the information of the two-dimensional numerical manifold of a nonlinear map.

Fields

• prob the problem TwoDManifoldProblem;
• data the numerical data that should be Vector{S}, where S is the interpolation curve (we use DataInterpolation in this package);
• flawpoints the flaw points generated during continuation.

TwoDManifoldProblem{F,T}

TwoDManifoldProblem is a struct to contain the main information for continuing the two-dimensional manifold of a nonlinear map.

Fields

• f the nonlinear map, which should has the form f(x,p) and return a SVector;
• para the parameters of the nonlinear map;
• amax the maximum angle between points when continuing the manifold;
• d the maximum distance between points when continuing the manifold;
• dcircle the maximum distance between circles when continuing the manifold;
• dsmin the minimum arc length allowing; note that if in a continuation point, this value is achieved and the angle as well as the distance values are not achieved, then we will record this point as a FlawPoint.

Convenient consturctors are TwoDManifoldProblem(f) and TwoDManifoldProblem(f,para)

VTwoDManifold{F,S,N,T}

VTwoDManifold is a struct contains all the information of the two-dimensional numerical manifold of an autonomous vector field.

Fields

• prob the problem VTwoDManifoldProblem;
• data the numerical data that should be Vector{S}, where S is the interpolation curve (we use DataInterpolation in this package);
• flawpoints the flaw points generated during continuation.

VTwoDManifoldProblem{F,T}

VTwoDManifoldProblem is a struct to contain the main information for continuing the two-dimensional manifold of an autonomous vector field.

Fields

• f the time flow map of the vector field, which should has the form f(x,p) and return a SVector; note that the vector field should be regularized, e.g., $\dot{x}=v(x)$ should be rewritten as $\dot{x}=v(x)/\sqrt{1+|v(x)|}$;
• para the parameters of the time flow map;
• amax the maximum angle between points when continuing the manifold;
• d the maximum distance between points when continuing the manifold;
• dsmin the minimum arc length allowing; note that if in a continuation point, this value is achieved and the angle as well as the distance values are not achieved, then we will record this point as a FlawPoint.

Convenient consturctors are VTwoDManifoldProblem(f) and VTwoDManifoldProblem(f,para)

InvariantManifolds.addcircles!(f, para, d, circles, dsmin, αmax, dcircle, flawpoints; interp=LinearInterpolation)

Adds and refines circles in the two-dimensional manifold computation by iterating the map and ensuring proper point distribution.

Arguments

• f: The nonlinear map function
• para: Vector of parameters for the map
• d: Maximum allowed distance between points in a circle
• circles: Vector of interpolated curves representing the current circles
• dsmin: Minimum allowed arc length between points
• αmax: Maximum allowed angle between consecutive points
• dcircle: Maximum allowed distance between consecutive circles
• flawpoints: Vector to store problematic points during computation
• interp: Interpolation method (default: QuadraticInterpolation)

Returns

A vector of new interpolated curves representing the refined circles after one iteration of the map.

Details

The function performs two main steps:

1. Iterates each circle forward under the map and refines point distribution within each circle
2. Adds intermediate circles where the distance between consecutive circles exceeds dcircle

Points are added to maintain proper spacing and curvature constraints specified by d and αmax.

InvariantManifolds.addpoints!(f, p, d, oldcurve, newu, olds, dsmin, αmax, flawpoints)

Add points to ensure proper spacing and curvature along a one-dimensional manifold curve.

Arguments

• f: The nonlinear map function
• p: Parameters for the nonlinear map
• d: Maximum allowed distance between consecutive points
• oldcurve: Previous curve interpolation
• newu::Vector{SVector{N,T}}: New points to be processed
• olds::Vector{T}: Parameter values of the points
• dsmin: Minimum allowed arc length between points
• αmax: Maximum allowed angle between consecutive segments
• flawpoints: Vector to store problematic points that don't meet criteria

Details

The function iteratively processes points, adding new ones when:

• The distance between consecutive points exceeds d
• The angle between consecutive segments exceeds αmax
• The arc length is greater than dsmin

If a point fails these criteria and the minimum arc length is reached, it's recorded as a flaw point.

Returns

Vector of parameter values for the new points

findsaddle(v, dv, timespan, x, p)

findsaddle is a function to find the saddle of the time-T-map of smooth ODE systems, by using the Newton's method.

Parameters

• v the vector field, which should be the form f(x,p,t) and return a SVector;
• dv the Jacobi matrix function of v, which should should be the form dv(x,p,t) and return a SMatrix;
• timespan the time span of the time-T-map;
• x the initial point to iterate.

Keyword arguments

• n maximum iterate times, default to be 100;
• abstol absolute tolerance for the fixed point, default to be 1e-8;
• alg the algorithm used to solve the ODE, default to be Vern9().

We also provide the finite difference method to find the saddle of the time-T-map of nonsmooth ODE systems:

Parameters

• setup the NSSetUp of the nonsmooth ODE system;
• x the initial point to iterate, of type SVector{N,T}.
• p the parameters of the nonsmooth ODE system.

Keyword arguments

• n maximum iterate times, default to be 100;
• abstol absolute tolerance for the fixed point, default to be 1e-8;

gen_disk(p, times)

gen_disk is a function to generate circles around the saddle, which represented as the local manifold.

Parameters

• p the struct Saddle which should contains two unstable directions; the complex eigenvalues and eigenvectors are allowed.

Keyword arguments

• times the iteration time, default to be 1; for the computation of invariant manifolds of nonlinear map, this parameter is needed to adjust the torsion in different directions in the process of continuation.
• n the number of point in each circle, default to be 150;
• d the max distance between points in a single circle, default to be 0.0002;
• r the size of the disk, default to be 0.05;
• circles the number of the circles, default to be 10.

gen_segment(saddle, direction)

Generating n points at saddle in the direction, with length d, with default n=50 and d=0.01. Another Convenient consturctor is gen_segment(p::Saddle).

grow!(manifold)

One time iteration to grow the manifold.

Parameters

• manifold the manifold struct.

Keyword argument

• interp the interpolation method used, default to be QuadraticInterpolation.

growmanifold(prob, points, N)

This is the mani function to continuate the numerical manifolds. Its output is a manifold struct.

Parameters

• prob the problem such as OneDManifoldProblem.
• points the points in the local manifold. For one dimensional manifolds, these points should be a Vector{SVector} and the start point should be the saddle. For two dimensional manifolds, these points should be a Vector{Vector{S}} and its first element should like [saddle, saddle, saddle]. Note that in the both cases, the functions gen_segment and gen_disk can generate these points easily.
• N the number of iterations.

Keyword argument

• interp the interpolation method used, default to be QuadraticInterpolation.

initialize(prob, points)

This is a function to initialize the continuation process. Its output is a manifold struct.

Parameters

• prob the problem such as OneDManifoldProblem.
• points the points in the local manifold. For one dimensional manifolds, these points should be a Vector{SVector} and the start point should be the saddle. For two dimensional manifolds, these points should be a Vector{Vector{S}} and its first element should like [saddle, saddle, saddle]. Note that in the both cases, the functions gen_segment and gen_disk can generate these points easily.

Keyword argument

• interp the interpolation method used, default to be QuadraticInterpolation.

iscontact(setup, saddle, para)

Check if the saddle point of the time-T-map has contacts with the hypersurfaces.

Parameters

• setup a NSSetUp.
• saddle a Saddle or a SVector.
• para the parameter of the vector field.

Returns

• true if the saddle point has contact with the hypersurfaces.
• false if the saddle point has no contact with the hypersurfaces.

InvariantManifolds.kd_distence

The function to measure the distance between two circles by using the package NearestNeighbors.jl.

InvariantManifolds.ns_addpoints!(tmap, p, d, dsmin, oldcurve, newu, olds, αmax, tend, hypers, ϵ, flawpoints) -> Vector{T}

Add points to ensure proper spacing and accuracy when computing the non-smooth one-dimensional manifold.

Arguments

• tmap: Time map function that evolves states forward
• p: Vector of parameters
• d: Maximum allowed distance between consecutive points
• dsmin: Minimum allowed arc length between points
• oldcurve: Previous curve data used for interpolation
• newu: Vector of new states to be processed
• olds: Vector of arc length parameters
• αmax: Maximum allowed angle between consecutive segments
• tend: End time of the time map
• hypers: Vector of hypersurface functions
• ϵ: Maximum allowed error in hypersurface intersection
• flawpoints: Vector to store problematic points encountered

Returns

• Vector of arc length parameters for the processed points

Details

The function adaptively adds points to maintain:

1. Maximum distance d between consecutive points
2. Maximum angle αmax between segments
3. Accuracy ϵ at hypersurface intersections

If constraints cannot be satisfied within dsmin, points are marked as flaws.

ns_solver(v::T, para, timespan, alg, N, T)

The function ns_solver is similar to timetmap. The output of this function is a function which maps a SVector to a NSSolution. This NSSolution contain all data of an non-smooth ODE solution.

Parameters

• v vector fields like PiecewiseV or BilliardV.
• para the parameter of the vector field.
• timespan the time span of the time-T-map.
• alg algorithm in OrdinaryDiffEq to solve ODE.
• N the dimension of the vector field.
• T number type used in computation.

To ensure type stable, the numbers in para and timespan should be type of T. The last two parameters have to be specified, since we need to store the event data.

Keyword arguments

• repeat_nudge=1//100 this is used to set the next testing point after a previously found zero.

For vector fields PiecewiseV and PiecewiseImpactV, we have two special keyword arguments:

• cross_time= 0.01 when the solution sol hits the hypersurface at time t, we need to know which domain it enters. We choose the state sol(t+cross_time) to determine which domain it enters.
• region_detect=_region_detect the region detect function to determine which domain the state in.

You can also pass the keywords of solve of OrdinaryDiffEq to this function, except the callback and saving related keywords.

setmap(v, timespan::Tuple{T,T}, alg) where {T}

The function setmap is to get a NSSetUp.

Parameters

• v a nonsmooth vector field like PiecewiseV or BilliardV.
• timespan the time span of the time-T-map.
• alg algorithm in OrdinaryDiffEq to solve ODE.

To ensure type stable, the numbers in timespan should be type of T.

Keyword arguments

• repeat_nudge=1//100 this is used to set the next testing point after a previously found zero.

For vector fields PiecewiseV and PiecewiseImpactV, we have two special keyword arguments:

• cross_time= 0.01 when the solution sol hits the hypersurface at time t, we need to know which domain it enters. We choose the state sol(t+cross_time) to determine which domain it enters.
• region_detect=_region_detect the region detect function to determine which domain the state in.

You can also pass the keywords of solve of OrdinaryDiffEq to this function, except the callback and saving related keywords.