From 0546483c52a098ff58407cb522e7962c17bd6e90 Mon Sep 17 00:00:00 2001 From: Omar Ashour Date: Thu, 11 Feb 2021 21:27:41 -0800 Subject: [PATCH] Update docs --- docs/make.jl | 6 ++++-- docs/src/index.md | 23 ++++++++++++----------- docs/src/man/examples.md | 4 ++-- docs/src/man/integrators.md | 3 +++ docs/src/man/visualization.md | 2 +- docs/src/{library.md => private.md} | 11 +++++------ docs/src/public.md | 18 ++++++++++++++++++ src/Darboux.jl | 15 ++++++++++++++- src/HirotaSolvers.jl | 26 +++++++++++--------------- src/SSSolvers.jl | 7 +++++++ src/Simulation.jl | 16 +++++++++++++++- src/Types.jl | 3 ++- 12 files changed, 94 insertions(+), 40 deletions(-) rename docs/src/{library.md => private.md} (55%) create mode 100644 docs/src/public.md diff --git a/docs/make.jl b/docs/make.jl index cfd8dec..dd28a33 100644 --- a/docs/make.jl +++ b/docs/make.jl @@ -13,10 +13,12 @@ makedocs(; ), pages=[ "Home" => "index.md", - "Integrators" => "man/integrators.md", "Examples" => "man/examples.md", "Visualization" => "man/visualization.md", - "Library" => "library.md", + "Library" => [ + "Public API" => "public.md", + "Internals" => "private.md", + "Integrators" => "man/integrators.md"] ], ) diff --git a/docs/src/index.md b/docs/src/index.md index f2e3d3c..559541f 100644 --- a/docs/src/index.md +++ b/docs/src/index.md @@ -1,22 +1,23 @@ ```@meta CurrentModule = NonlinearSchrodinger ``` -# NLSS +# NonlinearSchrodinger -*A suite of tools generator for the Nonlinear Schrodinger hierarchy.* +*A suite of tools for Nonlinear Schrodinger Equations* -A package for studying the nonlinear Schrodinger hierarchy's numerical and analytical solutions. This documentation is a work in progress and is very sparse at the moment. +`NonlinearSchrodinger.jl` is a suite of tools for solving Nonlinear Schrodinger equations via higher-order algorithms and Darboux transformations. ## Package Features -The current features are currently available or are a work in progress: +The following features are currently available: -- Solve the cubic nonlinear Schrodinger equation numerically using a variety of symplectic and Nystrom algorithms. -- Compute the integrals of motion (energy, momentum, and particle number) -- Compute the Darboux Transformation to study complicated analytical solutions +- Solving the cubic Nonlinear Schrodinger equation using a plethora of algortithms of order up to 8 (the number of algorithms available is always increasing!). Symplectic and Nystrom integrators are available. +- Solving the Hirota and Sasa-Satsuma equations using a combined split-step-finite-difference approach using a few different integrators. +- Computing the integrals of motion (energy, momentum, and particle number) and their errors. +- Computing the Darboux Transformation to study complicated analytical solutions. We currently support the breather and soliton seeds for extended nonlinear Schrodinger equations of order up to 5 (including cubic NLS, Hirota, LPD, Quintic, and arbitrary combinations thereof). We also support the `cn` and `dn` seeds for the cubic NLS. +- Easy [Visualization](@ref) through `Plots.jl` recipes. +- Very simple API that allows one to compute very complicated solutions via only a few lines of code. Some examples can be found on the [Examples](@ref) page. -Some examples can be found on the [Examples](@ref) page. For visualization of the solutions, see the [Visualization](@ref) page. -See the [Index](@ref main-index) for the complete list of documented functions and types. ```@contents Pages = [ "man/theory.md", @@ -27,11 +28,11 @@ Depth = 1 ## Library Outline ```@contents -Pages = ["library.md"] +Pages = ["public.md"] ``` ### [Index](@id main-index) ```@index -Pages = ["library.md"] +Pages = ["public.md"] ``` diff --git a/docs/src/man/examples.md b/docs/src/man/examples.md index 9a35014..19f1093 100644 --- a/docs/src/man/examples.md +++ b/docs/src/man/examples.md @@ -56,7 +56,7 @@ savefig("example2.svg") # hide ``` ![](example2.svg) -## Exampole 3: Nonlinear Talbot Carpet (Pruning) +## Example 3: Nonlinear Talbot Carpet (Pruning) ```@setup 3 using NonlinearSchrodinger using Plots @@ -158,7 +158,7 @@ savefig("example6.svg") #hide ``` ![](example6.svg) -## Example 7: First Order Breather mMtched to a ``dn`` Background +## Example 7: First Order Breather matched to a ``dn`` Background ```@setup 7 using NonlinearSchrodinger using Plots diff --git a/docs/src/man/integrators.md b/docs/src/man/integrators.md index cc9cdfd..b9dcc1d 100644 --- a/docs/src/man/integrators.md +++ b/docs/src/man/integrators.md @@ -32,4 +32,7 @@ T6A_OP! T6B_OP! T8A_OP! T8B_OP! +T1A_H! +T2A_H! +T1A_SS! ``` \ No newline at end of file diff --git a/docs/src/man/visualization.md b/docs/src/man/visualization.md index b0425ce..cf78458 100644 --- a/docs/src/man/visualization.md +++ b/docs/src/man/visualization.md @@ -69,4 +69,4 @@ savefig("recurse_4.svg") #hide ![](recurse_4.svg) -Note that the placement of the nodes is a little random, you might have to issue the plot command a few times to get a satisfactory result wheret he nodes don't overlap. \ No newline at end of file +Note that the placement of the nodes is a little random, you might have to issue the plot command a few times to get a satisfactory result where the nodes don't overlap. \ No newline at end of file diff --git a/docs/src/library.md b/docs/src/private.md similarity index 55% rename from docs/src/library.md rename to docs/src/private.md index 913d3e0..c593ce1 100644 --- a/docs/src/library.md +++ b/docs/src/private.md @@ -1,19 +1,18 @@ -# Library Documentation - -Documentation for `NonlinearSchrodinger.jl`'s library. +Documentation for `NonlinearSchrodinger.jl`'s internals. ## Contents ```@contents -Pages = ["library.md"] +Pages = ["private.md"] ``` ## Index ```@index -Pages = ["library.md"] +Pages = ["private.md"] ``` -## Functions +## API ```@autodocs Modules = [NonlinearSchrodinger] +Public = false Pages = ["Darboux.jl", "Simulation.jl", "Types.jl", "Utilities.jl"] ``` \ No newline at end of file diff --git a/docs/src/public.md b/docs/src/public.md new file mode 100644 index 0000000..5fdf600 --- /dev/null +++ b/docs/src/public.md @@ -0,0 +1,18 @@ +Documentation for `NonlinearSchrodinger.jl`'s public API. + +## Contents +```@contents +Pages = ["public.md"] +``` + +## Index +```@index +Pages = ["public.md"] +``` + +## API +```@autodocs +Modules = [NonlinearSchrodinger] +Private = false +Pages = ["Darboux.jl", "Simulation.jl", "Types.jl", "Utilities.jl"] +``` \ No newline at end of file diff --git a/src/Darboux.jl b/src/Darboux.jl index 613b8fe..69b856e 100644 --- a/src/Darboux.jl +++ b/src/Darboux.jl @@ -1,3 +1,10 @@ +""" + solve!(calc::Calc) + +Solves the object `sim::Calc`. + +See also: [`Calc`](@ref) +""" function solve!(calc::Calc) N = length(calc.λ) ψₜ = Array{Complex{Float64}}(undef, calc.box.Nₜ, calc.box.Nₓ, N+1) @@ -17,8 +24,14 @@ function solve!(calc::Calc) return nothing end -@memoize function calc_rs(c::Calc, n, p, ψₜ) +""" + calc_rs(c:Calc, n, p, ψₜ) +Calculate the lax pair generating functions recursively. See the paper for more details. + +See also: [`solve!`](@ref), [`Calc`](@ref) +""" +@memoize function calc_rs(c::Calc, n, p, ψₜ) @info "Calculating Lax pair generating functions rₙₚ(x,t) and sₙₚ(x,t) for (n,p) = ($n,$p)" # Base case if n == 1 diff --git a/src/HirotaSolvers.jl b/src/HirotaSolvers.jl index d28e076..7b372fe 100644 --- a/src/HirotaSolvers.jl +++ b/src/HirotaSolvers.jl @@ -1,11 +1,9 @@ """ - T₁ʰ(ψ, ω, dx, F) + T1A_H!(ψₒ, ψᵢ, dx, ops) -Compute `ψ'`, i.e. `ψ` advanced a step `dx` forward using a symplectic second order -integrator. `ψ'` is defined on an FFT grid with frequencies `ω` using an FFT plan -`F`. Do not call this explicitly and use `solve!` instead. +Compute `ψₒ`, i.e. `ψᵢ` advanced a step `dx` forward using a symplectic first order integrator of type A for the Hirota equation. The structure `ops::Operators` contains the FFT plans and the kinetic energy operators. -See also: [`solve!`](@ref) +See also: [`solve!`](@ref), [`Operators`](@ref) """ function T1A_H!(ψₒ, ψᵢ, dx, ops) # Nonlinear @@ -23,13 +21,11 @@ function T1A_H!(ψₒ, ψᵢ, dx, ops) end #T₁ʰ """ - T₂ʰ(ψ, ω, dx, F) + T2A_H!(ψₒ, ψᵢ, dx, ops) -Compute `ψ'`, i.e. `ψ` advanced a step `dx` forward using a symplectic second order -integrator. `ψ'` is defined on an FFT grid with frequencies `ω` using an FFT plan -`F`. Do not call this explicitly and use `solve!` instead. +Compute `ψₒ`, i.e. `ψᵢ` advanced a step `dx` forward using a symplectic second order integrator of type A for the Hirota equation. The structure `ops::Operators` contains the FFT plans and the kinetic energy operators. -See also: [`solve!`](@ref) +See also: [`solve!`](@ref), [`Operators`](@ref) """ function T2A_H!(ψₒ, ψᵢ, dx, ops) # Nonlinear @@ -37,17 +33,17 @@ function T2A_H!(ψₒ, ψᵢ, dx, ops) # Dispersion ops.F̂*ψₒ - ψₒ .= ops.K̂(dx/2) .* ψₒ # 3 allocs + ψₒ .= ops.K̂(dx/2) .* ψₒ ops.F̃̂*ψₒ # Burger - set_u!(ops.B̂, ψₒ) # 0 allocs - step!(ops.B̂) # 3-4 allocs - ψₒ .= ops.B̂.u # 2 allocs + set_u!(ops.B̂, ψₒ) + step!(ops.B̂) + ψₒ .= ops.B̂.u # Dispersion ops.F̂*ψₒ - ψₒ .= ops.K̂(dx/2) .* ψₒ # 3 allocs + ψₒ .= ops.K̂(dx/2) .* ψₒ ops.F̃̂*ψₒ # Nonlinear diff --git a/src/SSSolvers.jl b/src/SSSolvers.jl index 01bfeba..d43f409 100644 --- a/src/SSSolvers.jl +++ b/src/SSSolvers.jl @@ -1,3 +1,10 @@ +""" + T1A_SS!(ψₒ, ψᵢ, dx, ops) + +Compute `ψₒ`, i.e. `ψᵢ` advanced a step `dx` forward using a symplectic first order integrator of type A for the Sasa-Satsuma equation. The structure `ops::Operators` contains the FFT plans and the kinetic energy operators. + +See also: [`solve!`](@ref), [`Operators`](@ref) +""" function T1A_SS!(ψₒ, ψᵢ, dx, ops) # Nonlinear @. ψₒ = cis(-dx * (-1*abs2(ψᵢ)))*ψᵢ diff --git a/src/Simulation.jl b/src/Simulation.jl index 4dc670e..f81fb75 100644 --- a/src/Simulation.jl +++ b/src/Simulation.jl @@ -5,7 +5,7 @@ include("SSSolvers.jl") """ solve!(sim::Sim) -Solves the `Sim` object `sim`. +Solves the object `sim::Sim`. See also: [`Sim`](@ref) """ @@ -35,6 +35,13 @@ function solve!(sim::Sim) @info "Computation Done!" end #solve +""" + soln_loop_A(sim, ops, ind_p)) + +Propagate in `x` for integrators of type `A` (i.e. starting with nonlinear step, thus in real space). + +See also: [`Sim`](@ref), [`solve!`](@ref) +""" function soln_loop_A(sim, ops, ind_p) for i = 1:sim.box.Nₓ-1 @views sim.T̂(sim.ψ[:, i+1], sim.ψ[:, i], sim.box.dx, ops) @@ -51,6 +58,13 @@ function soln_loop_A(sim, ops, ind_p) sim.ψ̃ .= fftshift(fft(sim.ψ, 1), 1)./sim.box.Nₜ end +""" + soln_loop_B(sim, ops, ind_p)) + +Propagate in `x` for integrators of type `B` (i.e. starting with dispersion step, thus in frequency space). + +See also: [`Sim`](@ref), [`solve!`](@ref) +""" function soln_loop_B(sim, ops, ind_p) F̃̂ = plan_ifft(@view sim.ψ[:, 1]) F̂ = plan_fft(@view sim.ψ[:, 1]) diff --git a/src/Types.jl b/src/Types.jl index 5d8373b..09e8483 100644 --- a/src/Types.jl +++ b/src/Types.jl @@ -1,4 +1,3 @@ - struct Box{TT<:Real} t::Array{TT, 1} ω::Array{TT, 1} @@ -122,6 +121,8 @@ Create a `::Calc` object with eigenvalues `λ`, shifts `xₛ` and `tₛ` and see `seed = "cn"` ``\\implies \\psi_0 = \\sqrt{m}cn(t, m)e^{ix(m - 1/2)}`` +`f::Dict{Symbol, Float64}` is a dictionary of extended NLSE parameters. + See also: [`Box`](@ref) """ function Calc(λ::Array{Complex{TT}}, tₛ, xₛ, seed, box; m=0.0, f = Dict(:α=>0.0, :γ=>0.0,:δ=> 0.0)) where TT <: Real