Major overhaul (#8)

* Define vector potential, find amplitude via AD; cos² envelope

* Fixed phase_shift

* No units are now interpreted as atomic units

* Computations now done exclusively in atomic units; implemented specialized ConstantField

* Fixed {Wrapped,Padded}Field

* Correct vector potential for ConstantField

* Removed Printf dependency

* Added WindowedField

* Pretty printing

* Added explanation

* WIP Support for transverse fields

* Minor fixes

* Added free_oscillation_amplitude

* Removed @time

* Cleaned up types a bit

* Another unit helper

* Introduced Polarization trait

* Make timeaxis work for SumFields

* Fix span(::DelayedField)

* Implement computation of fluence

* Misc

* Correct computation of intensity for TransverseFields

* Correct computation of intensity for arbitrary fields

* Ensure rotation is always SMatrix; allow arbitrary rotation matrices

* Improved printing of polarized fields and rounding of units

* Simplified evaluation of amplitude and vector potential at many times

* Added base unit for vector potential

* Fixed method ambiguity for SumField

* ponderomotive_potential

* Fixed PaddedField

* Don't force TruncatedGaussianEnvelope duraiton to integer number of cycles

* Misc

* Allow specification of time axis through number of time steps and step size

* Fix units error

* Fixed PaddedField for arbitrary polarization

* rotation_matrix

* Misc

* Support analytic continuation into the complex plane

* Compat bounds

* Also run CI on latest Julia 1.x

* Update paths

* Run doctests in a separate job

* Fixed some tests, disabled Sellmeier tests for now

* Tests of units

* Fix units tests

* Gaussian pulses tests

* Some documentation

* Fixed bug in computing rotation axis

* Some more documentation

* Test rotations

* Test strong-field properties

* span now returns an Interval

* Field arithmetic

* Make timeaxis use new range(::Interval) functionality

* Envelopes tests

* Carriers tests

* Constant fields tests

* Test various field types

* Some documentation

* Test competing quantities

* Print strong field properties for the basic field types

* Test string representation of arithmetic fields

* Remove unused code

* Fix documentation

* One more test

* Allow doctests to fail the build, since they now actually pass

* Improve analytic continuation of fields

.github/workflows/ci.yml

@@ -11,6 +11,7 @@ jobs:
       matrix:
         version:
           - '1.5'
+          - '1'
           - 'nightly'
         os:
           - ubuntu-latest
@@ -47,18 +48,39 @@ jobs:
       - uses: actions/checkout@v2
       - uses: julia-actions/setup-julia@v1
         with:
-          version: '1.5'
+          version: '1'
       - run: |
           julia --project=docs -e '
             using Pkg
+            pkg"add PyCall PyPlot https://github.com/jagot/Jagot.jl.git"
             Pkg.develop(PackageSpec(path=pwd()))
             Pkg.instantiate()'
-      - run: |
-          julia --project=docs -e '
-            using Documenter: doctest
-            using ElectricFields
-            doctest(ElectricFields)'
+        env:
+          PYTHON: ""
       - run: julia --project=docs docs/make.jl
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
           DOCUMENTER_KEY: ${{ secrets.DOCUMENTER_KEY }}
+  doctests:
+    name: Doctests
+    runs-on: macOS-latest
+    steps:
+      - uses: actions/checkout@v2
+      - uses: julia-actions/setup-julia@v1
+        with:
+          version: '1'
+      - run: |
+          julia --project=docs -e '
+            using Pkg
+            Pkg.develop(PackageSpec(path=pwd()))
+            Pkg.instantiate()'
+      - name: Run Doctests
+        # # See https://github.com/actions/toolkit/issues/399
+        # continue-on-error: true
+        run: |
+          julia --project=docs -e '
+            using Documenter: DocMeta, doctest
+            using ElectricFields
+            DocMeta.setdocmeta!(ElectricFields, :DocTestSetup, :(using ElectricFields, Unitful); recursive=true)
+            doctest(ElectricFields)'
+

.gitignore

@@ -2,4 +2,5 @@
 *.jl.*.cov
 *.jl.mem
 /docs/build/
-Manifest.toml
+Manifest.toml
+/docs/src/figures/

Project.toml

@@ -4,17 +4,26 @@ authors = ["Stefanos Carlström <[email protected]>"]
 version = "0.1.0"
 
 [deps]
-Calculus = "49dc2e85-a5d0-5ad3-a950-438e2897f1b9"
 FFTW = "7a1cc6ca-52ef-59f5-83cd-3a7055c09341"
+Formatting = "59287772-0a20-5a39-b81b-1366585eb4c0"
+ForwardDiff = "f6369f11-7733-5829-9624-2563aa707210"
+IntervalSets = "8197267c-284f-5f27-9208-e0e47529a953"
+LinearAlgebra = "37e2e46d-f89d-539d-b4ee-838fcccc9c8e"
+Optim = "429524aa-4258-5aef-a3af-852621145aeb"
 Parameters = "d96e819e-fc66-5662-9728-84c9c7592b0a"
-Printf = "de0858da-6303-5e67-8744-51eddeeeb8d7"
+StaticArrays = "90137ffa-7385-5640-81b9-e52037218182"
 Unitful = "1986cc42-f94f-5a68-af5c-568840ba703d"
 UnitfulAtomic = "a7773ee8-282e-5fa2-be4e-bd808c38a91a"
 
 [compat]
-FFTW = "1.2"
+FFTW = "1.3"
+Formatting = "0.4"
+ForwardDiff = "0.10"
+IntervalSets = "0.5.3"
+Optim = "1.3"
 Parameters = "0.12"
-Unitful = "1.4"
+StaticArrays = "1.1"
+Unitful = "1.7"
 UnitfulAtomic = "1.0"
 julia = "1.5"
 

README.org

@@ -2,8 +2,8 @@
 #+AUTHOR: Stefanos Carlström
 #+EMAIL: [email protected]
 
-[[https://jagot.github.io/ElectricFields.jl/stable][https://img.shields.io/badge/docs-stable-blue.svg]]
-[[https://jagot.github.io/ElectricFields.jl/dev][https://img.shields.io/badge/docs-dev-blue.svg]]
+[[https://www.tipota.org/ElectricFields.jl/stable][https://img.shields.io/badge/docs-stable-blue.svg]]
+[[https://www.tipota.org/ElectricFields.jl/dev][https://img.shields.io/badge/docs-dev-blue.svg]]
 [[https://github.com/jagot/ElectricFields.jl/actions][https://github.com/jagot/ElectricFields.jl/workflows/CI/badge.svg]]
 [[https://codecov.io/gh/jagot/ElectricFields.jl][https://codecov.io/gh/jagot/ElectricFields.jl/branch/master/graph/badge.svg]]
 
@@ -12,62 +12,12 @@
 A small Julian DSL for defining electrical fields, chiefly for use in
 atomic physics calculations.
 
-
-#+BEGIN_SRC julia :exports none
-  using Unitful
-  using PyPlot
-  matplotlib[:style][:use]("ggplot")
-
-  mkpath("images")
-
-  function savefig_f(filename)
-      filename = "./images/$(filename).svg"
-      savefig(filename, transparent=true)
-      filename
-  end
-#+END_SRC
-
-#+RESULTS:
-: savefig_f (generic function with 1 method)
-
-* Usage
- First we load the library and set the base units, which are used if
- unitless quantities are passed to =@field=, below. The units are
- defined in the fashion of [[https://github.com/ajkeller34/Unitful.jl][Unitful.jl]].
- #+BEGIN_SRC julia :exports code
-   using ElectricFields
-
-   # These are the default base units, so setting these is actually not
-   # necessary, if you are happy with the defaults.
-   @set_base_units() do
-       λ  = u"nm"
-       I₀ = u"W/cm^2"
-       τ  = u"fs"
-   end
- #+END_SRC
-
- #+RESULTS:
- : nothing
-
- We can now define a field, which we name =IR=, using the =@field=
- macro:
- #+BEGIN_SRC julia :exports both :results value verbatim
-   @field(IR) do
-       λ    = 800.0
-       I₀   = 1e14
-       τ    = 6.2
-       Tmax = 10
-   end
- #+END_SRC
-
- #+RESULTS:
- : Linearly polarized field with a
- :   Fixed carrier @ λ = 800.00 nm (T = 2.67 fs) and a
- :   I₀ = 1e+14 cm^-2 W Gaussian envelope of duration 6.2 fs (intensity FWHM; ±10.14σ)
-
- More usage examples are found [[file:src/ElectricFields.org][within the code]].
-
-* Ideas
-  - Harmonic fields
-  - Chirped/dispersed fields
-  - Elliptically polarized fields
+It is not intended to be used in the computations /of/, but rather
+/with/ electric fields, i.e. the electric fields are input parameters
+to (boundary terms of) a time-dependent calculation. Furthermore, the
+fields are not solutions to the full Maxwell equations, but to the
+paraxial approximation, which means that they are propagating along
+one direction and polarized in a plane transverse to the direction of
+propagation. One may however add multiple fields propagating in
+different directions forming a field vector that is not confined to a
+single plane.

docs/Project.toml

@@ -1,2 +1,9 @@
 [deps]
 Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
+Unitful = "1986cc42-f94f-5a68-af5c-568840ba703d"
+UnitfulAtomic = "a7773ee8-282e-5fa2-be4e-bd808c38a91a"
+
+[compat]
+Documenter = "0.26"
+Unitful = "1.7"
+UnitfulAtomic = "1.0"

docs/make.jl

@@ -1,19 +1,42 @@
 using ElectricFields
 using Documenter
 
+isdefined(Main, :NOPLOTS) && NOPLOTS || include("plots.jl")
+
 makedocs(;
     modules=[ElectricFields],
     authors="Stefanos Carlström <[email protected]> and contributors",
     repo="https://github.com/jagot/ElectricFields.jl/blob/{commit}{path}#L{line}",
     sitename="ElectricFields.jl",
     format=Documenter.HTML(;
         prettyurls=get(ENV, "CI", "false") == "true",
-        canonical="https://jagot.github.io/ElectricFields.jl",
+        canonical="https://www.tipota.org/ElectricFields.jl",
         assets=String[],
+        mathengine = MathJax(Dict(
+            :TeX => Dict(
+                :equationNumbers => Dict(:autoNumber => "AMS"),
+                :Macros => Dict(
+                    :defd => "≝",
+                    :abs => ["\\left|#1\\right|", 1],
+                    :vec => ["\\mathbf{#1}", 1],
+                    :mat => ["\\mathsf{#1}", 1],
+                    :conj => ["#1^*", 1],
+                    :im => "\\mathrm{i}",
+                    :diff => ["\\mathrm{d}#1\\,", 1],
+                    :bmat => ["\\begin{bmatrix}#1\\end{bmatrix}", 1]
+                )
+            )
+        ))
     ),
     pages=[
         "Home" => "index.md",
+        "Field types" => "field_types.md",
+        "Envelopes" => "envelopes.md",
+        "Carriers" => "carriers.md",
+        "Field properties" => "properties.md",
+        "Reference" => "reference.md",
     ],
+    doctest=false
 )
 
 deploydocs(;

docs/plots.jl

@@ -0,0 +1,109 @@
+using ElectricFields
+using Unitful
+
+using PyPlot
+using Jagot.plotting
+plot_style("ggplot")
+
+function savedocfig(name,dir="figures")
+    fig = gcf()
+    filename = joinpath(@__DIR__, "src", dir, "$(name).svg")
+    savefig(filename,
+            transparent=true,
+            facecolor=fig.get_facecolor())
+    close(fig)
+    if isfile(filename)
+        println("Saved $(name) to $(filename)")
+    else
+        @warn "Saving $(name) to $(filename) failed"
+    end
+end
+
+function savedfigure(fun::Function, name, args...; kwargs...)
+    cfigure(name, args...; kwargs...) do
+        fun()
+    end
+    savedocfig(name)
+end
+
+function index_example()
+    @field(IR) do
+        I₀ = 1e14u"W/cm^2"
+        λ = 800.0u"nm"
+        τ = 6.2u"fs"
+        σmax = 6.0
+    end
+    t = timeaxis(IR)
+    tplot = 24.3e-3t
+    Fv = field_amplitude(IR, t)
+    Fenv = field_envelope.(IR, t)
+    Av = vector_potential(IR, t)
+    Iv = instantaneous_intensity.(IR, t)
+    Ienv = intensity.(IR, t)
+
+    savedfigure("index_example") do
+        csubplot(311, nox=true) do
+            plot(tplot, Av)
+            ylabel(L"$A(t)$ [au]")
+        end
+        csubplot(312, nox=true) do
+            plot(tplot, Fv)
+            plot(tplot, Fenv)
+            ylabel(L"$F(t)$ [au]")
+        end
+        csubplot(313) do
+            plot(tplot, Iv)
+            plot(tplot, Ienv)
+            ylabel(L"$I(t)$ [au]")
+        end
+        xlabel(L"$t$ [fs]")
+    end
+end
+
+function index_polarized_example()
+    @field(A) do
+        I₀ = 1.0
+        ω = 1.0
+        cycles = 6.0
+        env = :cos²
+        ξ = 1.0
+    end
+
+    @field(B) do
+        I₀ = 1.0
+        ω = 2.0
+        cycles = 6.0
+        env = :cos²
+        ξ = -1.0
+    end
+
+    F = A + delay(B, 3/2π)
+
+    t = timeaxis(F)
+    Fv = field_amplitude(F, t)
+
+    savedfigure("index_polarized_example", figsize=(8,10)) do
+        csubplot(211) do
+            plot(t, Fv[:,1], label=L"F_x(t)")
+            plot(t, Fv[:,3], label=L"F_z(t)")
+            legend()
+            xlabel(L"$t$ [jiffies]")
+        end
+        csubplot(212, projection="3d") do
+            plot3D(t, Fv[:,1], Fv[:,3])
+            xlabel(L"$t$ [jiffies]")
+            ylabel(L"F_x(t)")
+            gca().set_zlabel(L"F_z(t)")
+        end
+    end
+end
+
+macro echo(expr)
+    println(expr)
+    :(@time $expr)
+end
+
+@info "Documentation plots"
+mkpath("docs/src/figures")
+@echo index_example()
+@echo index_polarized_example()

docs/src/carriers.md

@@ -0,0 +1,10 @@
+# Carriers
+
+```@docs
+ElectricFields.AbstractCarrier
+ElectricFields.LinearCarrier
+ElectricFields.FixedCarrier
+ElectricFields.TransverseCarrier
+ElectricFields.LinearTransverseCarrier
+ElectricFields.EllipticalCarrier
+```

docs/src/envelopes.md

@@ -0,0 +1,12 @@
+# Envelopes
+
+The various envelopes require different parameters to be specified in
+the [`@field`](@ref) creation macro; they are listed below with `σ|τ`
+implying that either `σ` _or_ `τ` is required.
+
+```@docs
+ElectricFields.GaussianEnvelope
+ElectricFields.TruncatedGaussianEnvelope
+ElectricFields.TrapezoidalEnvelope
+ElectricFields.Cos²Envelope
+```

docs/src/field_types.md

@@ -0,0 +1,18 @@
+# Field types
+
+## Basic field types
+```@docs
+ElectricFields.LinearField
+ElectricFields.TransverseField
+ElectricFields.ConstantField
+```
+
+## Arithmetic
+```@docs
+ElectricFields.SumField
+ElectricFields.WrappedField
+ElectricFields.NegatedField
+ElectricFields.DelayedField
+ElectricFields.PaddedField
+ElectricFields.WindowedField
+```