Update documentation

docs/make.jl

@@ -13,7 +13,12 @@ makedocs(;
     ),
     pages=[
         "Home" => "index.md",
-        "Examples" => "man/examples.md",
+        "Theory" => [
+            "Simulations" => "man/simulations.md",
+            "Darboux Transformations" =>  "man/dt.md"],
+        "Examples" => [
+            "Simulation Examples" => "man/sim_examples.md",
+            "DT Examples" =>  "man/dt_examples.md"],
         "Visualization" => "man/visualization.md",
         "Library" => [
             "Public API" => "public.md",

docs/src/index.md

@@ -15,20 +15,21 @@ The following features are currently available:
 - 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.
+- Very simple API that allows one to compute very complicated solutions via only a few lines of code.
 
 
+## Examples
 ```@contents
 Pages = [
-    "man/theory.md",
+    "man/dt_examples.md",
 ]
-Depth = 1
+Depth = 2
 ```
-
-## Library Outline
-
 ```@contents
-Pages = ["public.md"]
+Pages = [
+    "man/sim_examples.md",
+]
+Depth = 2
 ```
 
 ### [Index](@id main-index)

docs/src/man/dt.md

@@ -0,0 +1,25 @@
+# Darboux Transformations
+
+Please see the paper to review the theory of Darboux Trasformations, and the [Darboux Transformation Examples](@ref) page for examples.
+
+## Supported Equations
+
+The most general equation supported by the Darboux transformation in `NonlinearSchrodinger.jl` is of the following form:
+
+```math
+i{\psi _x} + S[\psi (x,t)] - i\alpha H[\psi (x,t)] + \gamma P[\psi (x,t)] - i\delta Q[\psi (x,t)] = 0,
+```
+
+where
+```math
+\begin{aligned}
+S[\psi (x,t)] &= \frac{1}{2}{\psi _{tt}} + {\left| \psi  \right|^2}\psi, \\
+H[\psi (x,t)] &= {\psi _{ttt}} + 6{\left| \psi  \right|^2}{\psi _t}, \\
+P[\psi (x,t)] &= {\psi _{tttt}} + 8{\left| \psi  \right|^2}{\psi _{tt}} + 6{\left| \psi  \right|^4}\psi + 4{\left| {{\psi _t}} \right|^2}\psi + 6{\psi _t}^2{\psi ^*} + 2{\psi ^2}\psi _{tt}^*, \\
+Q[\psi (x,t)] &= {\psi _{ttttt}} + 10{\left| \psi  \right|^2}{\psi _{ttt}} + 30{\left| \psi  \right|^4}{\psi _t} + 10\psi {\psi _t}\psi _{tt}^* + 10\psi \psi _t^*{\psi _{tt}} + 20{\psi ^*}{\psi _t}{\psi _{tt}} + 10\psi _t^2\psi _t^*.
+\end{aligned}
+```
+
+Special cases include the cubic nonlinear Schrodinger equation (``\alpha = \gamma = \delta = 0``), the Hirota equation (``\alpha \neq 0, \gamma = \delta = 0``) the Lakshmanan-Porsezian-Daniel (LPD) equation (``\gamma \neq 0, \alpha = \delta = 0``) and the Quintic nonlinear Schrodinger equation (``\delta \neq 0, \alpha = \gamma = 0``).
+
+For this generalized NLSE, we support both the breather and soliton seeds. Additionally, for the cubic NLSE, we support the ``cn`` and ``dn`` seeds. Support for these seeds will be added at some point in the future for the generalized NLSE.

docs/src/man/dt_examples.md

@@ -0,0 +1,103 @@
+# Darboux Transformation Examples
+
+## Example 1: 7 Soliton Collision
+```@setup 1
+using NonlinearSchrodinger
+using Plots
+using LaTeXStrings
+```
+
+```@example 1
+xᵣ = -10=>10
+T = 20
+seed = "0"
+box = Box(xᵣ, T, Nₓ=500, Nₜ = 500)
+λ = [-0.45 + 0.775im, -0.35 + 0.8im, -0.25 + 0.825im, 0.85im, 0.25 + 0.875im, 0.35 + 0.9im, 0.45 + 0.925im]
+xₛ = [0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0]
+tₛ = [0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0]
+
+calc = Calc(λ, tₛ, xₛ, seed, box) 
+
+solve!(calc)
+heatmap(calc) 
+savefig("example1.svg") #hide
+```
+![](example1.svg)
+
+## Example 2: Fifth Order Maximal Intensity Breather
+```@setup 2
+using NonlinearSchrodinger
+using Plots
+using LaTeXStrings
+```
+
+```@example 2
+xᵣ = -10=>10
+λ₁ = 0.98im
+λ, T, Ω = params(λ = λ₁)
+box = Box(xᵣ, T, Nₓ=500, Nₜ = 500, n_periods = 3)
+
+λ = λ_maximal(λ₁, 5) # array of 5 eigenvalues
+xₛ = [0.0, 0.0, 0.0, 0.0, 0.0]
+tₛ = [0.0, 0.0, 0.0, 0.0, 0.0]
+
+seed = "exp"
+calc = Calc(λ, tₛ, xₛ, seed, box) 
+
+solve!(calc)
+surface(calc) 
+savefig("example2.svg") #hide
+```
+![](example2.svg)
+
+## Example 3: 3 Soliton Collision on a ``cn`` background
+```@setup 3
+using NonlinearSchrodinger
+using Plots
+using LaTeXStrings
+```
+
+```@example 3
+xᵣ = -10=>10
+T = 20
+
+box = Box(xᵣ, T, Nₓ=500, Nₜ = 500, n_periods = 1)
+λ = [-0.3+0.85im, 0.9im, 0.3+0.95im]
+xₛ = [0.0, 0.0, 0.0]
+tₛ = [0.0, 0.0, 0.0]
+
+seed = "cn"
+calc = Calc(λ, tₛ, xₛ, seed, box, m = 0.5) 
+
+solve!(calc)
+surface(calc) 
+savefig("example3.svg") #hide
+```
+![](example3.svg)
+
+## Example 4: First Order Breather matched to a ``dn`` Background
+```@setup 4 
+using NonlinearSchrodinger
+using Plots
+using LaTeXStrings
+```
+
+```@example 4
+xᵣ = -10=>10
+m = 2/5
+λ = λ_given_m(m, q=4)
+λ, T, Ω = params(λ = λ, m=m)
+box = Box(xᵣ, T, Nₓ=500, Nₜ = 500, n_periods = 3)
+
+λ = λ_maximal(λ, 1, m=m)
+xₛ = [0.0]
+tₛ = [0.0]
+
+seed = "dn"
+calc = Calc(λ, tₛ, xₛ, seed, box, m=m) 
+
+solve!(calc)
+heatmap(calc) 
+savefig("example4.svg") #hide
+```
+![](example4.svg)

docs/src/man/integrators.md

@@ -1,5 +1,5 @@
 # Integrators
-This page shows the availabe integrators.
+This page shows the availabe integrators. Integrators prefixed with `_H` are used for the Hirota equation, and those with `_SS` are for the Sasa-Satsuma equation. Note that both these equations are not fully tested and should be used with utmost care due to the periodic boundary conditions.
 
 ```@index
 Pages = ["integrators.md"]