initial commit

Author: jkosata

.gitignore

@@ -0,0 +1,11 @@
+Manifest.toml
+examples/.ipynb_checkpoints/**
+examples/dev_tests/.ipynb_checkpoints/**
+examples/local/**
+data/**
+local_tests
+.vscode/**
+.DS_Store
+.DS_Store
+docs/build/**
+examples/jdp.mplstyle

Project.toml

@@ -0,0 +1,36 @@
+name = "HarmonicBalance"
+uuid = "e13b9ff6-59c3-11ec-14b1-f3d2cc6c135e"
+authors = ["Jan Kosata <kosataj@phys.ethz.ch>", "Javier del Pino <jdelpino@phys.ethz.ch>"]
+version = "0.3.0"
+
+[deps]
+BijectiveHilbert = "91e7fc40-53cd-4118-bd19-d7fcd1de2a54"
+Conda = "8f4d0f93-b110-5947-807f-2305c1781a2d"
+DSP = "717857b8-e6f2-59f4-9121-6e50c889abd2"
+DataFrames = "a93c6f00-e57d-5684-b7b6-d8193f3e46c0"
+DataStructures = "864edb3b-99cc-5e75-8d2d-829cb0a9cfe8"
+DifferentialEquations = "0c46a032-eb83-5123-abaf-570d42b7fbaa"
+Distances = "b4f34e82-e78d-54a5-968a-f98e89d6e8f7"
+DocStringExtensions = "ffbed154-4ef7-542d-bbb7-c09d3a79fcae"
+Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
+FFTW = "7a1cc6ca-52ef-59f5-83cd-3a7055c09341"
+Gtk = "4c0ca9eb-093a-5379-98c5-f87ac0bbbf44"
+HomotopyContinuation = "f213a82b-91d6-5c5d-acf7-10f1c761b327"
+JLD2 = "033835bb-8acc-5ee8-8aae-3f567f8a3819"
+LaTeXStrings = "b964fa9f-0449-5b57-a5c2-d3ea65f4040f"
+Latexify = "23fbe1c1-3f47-55db-b15f-69d7ec21a316"
+LinearAlgebra = "37e2e46d-f89d-539d-b4ee-838fcccc9c8e"
+Peaks = "18e31ff7-3703-566c-8e60-38913d67486b"
+Polyester = "f517fe37-dbe3-4b94-8317-1923a5111588"
+Printf = "de0858da-6303-5e67-8744-51eddeeeb8d7"
+PyCall = "438e738f-606a-5dbb-bf0a-cddfbfd45ab0"
+PyPlot = "d330b81b-6aea-500a-939a-2ce795aea3ee"
+REPL = "3fa0cd96-eef1-5676-8a61-b3b8758bbffb"
+RecursiveArrayTools = "731186ca-8d62-57ce-b412-fbd966d074cd"
+SymbolicUtils = "d1185830-fcd6-423d-90d6-eec64667417b"
+Symbolics = "0c5d862f-8b57-4792-8d23-62f2024744c7"
+
+[compat]
+Polyester = ">= 0.4.2"
+Symbolics = ">=3.4.3"
+julia = ">=1.7.0"

README.md

@@ -0,0 +1,7 @@
+# HarmonicBalance.jl
+
+## Installation
+
+## Example
+
+## Authors

docs/make.jl

@@ -0,0 +1,24 @@
+using Pkg
+current_path = @__DIR__
+Pkg.activate(current_path * "/../.");
+
+using Documenter, HarmonicBalance
+
+makedocs(
+	sitename="HarmonicBalance.jl",
+	#format = Documenter.HTML(assets = [])
+	pages = [
+		"Examples" => Any[
+			"examples/ex1.md"
+			"examples/ex2.md"
+			],
+		"Manual" => Any[
+			"manual/entering_eom.md"
+			"manual/extracting_harmonics.md"
+			"manual/solving_harmonics.md"
+			"manual/plotting.md"
+			"manual/time_dependent.md"
+			"manual/linear_response.md"
+			]
+		]
+)

docs/src/assets/logo.png

@@ -0,0 +1,63 @@
+# Example 1
+
+some text
+
+markdown: 
+```julia
+using HarmonicBalance.jl
+```
+
+First, we need to define the symbolic variables to be used. The syntax here is inherited from Symbolics.jl
+```julia
+@variables
+```
+
+These are used to define an equation of motion
+```julia
+dEOM = HarmonicBalance.DifferentialEquation
+```
+
+This object now holds the equations and identifies its variables.
+
+Now we must specify which harmonics will be used to expand which variable, let's start with using the single
+```julia
+HarmonicBalance.add_harmonic!(dEOM, x, ω)
+```
+
+The problem is now fully specified - we may convert the differential equation into a 
+```julia
+averagedEOM
+```
+
+We may now inspect the generated equations. The conversion has generated new variables describing each harmonic.
+```julia
+averagedEOM.equations
+```
+
+This object is the central point of the HarmonicBalance.jl framework. It may be fed into an algebraic or a time-dependent solver. 
+
+```julia
+averagedEOM
+```
+
+We are now ready to use the homotopy continuation method to obtain all the solutions of our algebraic equations. This is typically done across a set of parameters.
+
+```julia
+ParameterRange
+get_steady_states
+```
+
+
+So far, the equation have been relatively uncomplicated. However, due to the presence of the cubic nonlinearity, the ansatz ...      $`3ω`$ does not fully describe the behaviour of our system. Frequency conversion - to first order, from ω to 3ω - will occur. To see the effect of this, we may expand the motion in both harmonics.
+```julia
+HarmonicBalance.add_harmonic!(dEOM, x, [ω, 3ω])
+```
+
+The generated equations are not perturbative - all harmonics are treated on the same footing. The newly generated variables are (pretty print of VDP types). Proceeding to a solution diagram as before, we may now plot the two harmonics separately.
+
+
+We see that, although the third harmonic is clearly present, our solution landscape did not change much. In later examples, we will see this is not always the case. 
+
+
+
+To sort: hyperlinks

docs/src/examples/ex1.md

@@ -0,0 +1 @@
+# Example 2

docs/src/examples/ex2.md

@@ -0,0 +1,5 @@
+# Home
+
+This is the main page
+
+## Installation

docs/src/index.md

@@ -0,0 +1,13 @@
+# Entering equations of motion 
+
+The struct `DifferentialEquation` is the primary input method; it holds an ODE or a coupled system of ODEs. The dependent variables are specified during input, any other symbols
+are identified as parameters. Information on which variable is to be expanded in which harmonic is specified using `add_harmonic!`. 
+
+`DifferentialEquation.equations` stores a dictionary assigning variables to equations. This is because the harmonics belonging to a variable are later used to Fourier-transform its corresponding ODE.
+
+```@docs
+DifferentialEquation
+add_harmonic!
+get_variables(::DifferentialEquation)
+get_independent_variables(::DifferentialEquation)
+```

docs/src/manual/entering_eom.md

@@ -0,0 +1,28 @@
+# Extracting harmonic equations
+
+Once a `DifferentialEquation` is defined and its harmonics specified, one can extract the harmonic equations using `get_harmonic_equations`, which itself is composed of the subroutines `harmonic_ansatz`, `slow_flow`, `fourier_transform!` and `drop_powers`. 
+
+
+```@docs
+get_harmonic_equations
+HarmonicBalance.harmonic_ansatz
+HarmonicBalance.slow_flow
+HarmonicBalance.fourier_transform
+HarmonicBalance.drop_powers
+```
+
+## HarmonicVariable and HarmonicEquation types
+
+The equations governing the harmonics are stored using the two following structs. When going from the original to the harmonic equations, the harmonic ansatz $x_i(t) = \sum_{j=1}^M u_i^{(j)}  (T)  \cos(\omega_j^{(i)} t)+ v_i^{(j)} (T) \sin(\omega_j^{(i)} t)$ is used. Internally, each pair $(u_i^{(j)}, v_i^{(j)})$ is stored as a `HarmonicVariable`. This includes the identification of $\omega_j^{(i)}$ and $x_i(t)$, which is needed to later reconstruct the solutions in the non-rotating frame.
+
+```@docs
+HarmonicVariable
+```
+
+When the full set of equations of motion is expanded using the harmonic ansatz, the result is stored as a `HarmonicEquation`. For an initial equation of motion consisting of $M$ variables, each expanded in $N$ harmonics, the resulting `HarmonicEquation` holds $2NM$ equations of $2NM$ variables. Each symbol not corresponding to a variable is identified as a parameter. 
+
+A `HarmonicEquation` can be either parsed into a steady-state `Problem` or solved using a dynamical ODE solver.
+
+```@docs
+HarmonicEquation
+```