Refac laser beam

Project.toml

@@ -1,7 +1,7 @@
 name = "LaserExperiments"
 uuid = "eb1875a3-6e0d-577e-a250-3e610cb08925"
-authors = ["Uwe Hernandez Acosta <u.hernandez@hzdr.de>"]
 version = "0.1.0"
+authors = ["Uwe Hernandez Acosta <u.hernandez@hzdr.de>"]
 
 [deps]
 LinearAlgebra = "37e2e46d-f89d-539d-b4ee-838fcccc9c8e"
@@ -19,8 +19,10 @@ Unitful = "1.25.0"
 julia = "1.10"
 
 [extras]
+DrWatson = "634d3b9d-ee7a-5ddf-bec9-22491ea816e1"
 Random = "9a3f8284-a2c9-5f02-9a11-845980a1fd5c"
+SafeTestsets = "1bc83da4-3b8d-516f-aca4-4fe02f6d838f"
 Test = "8dfed614-e22c-5e08-85e1-65c5234f0b40"
 
 [targets]
-test = ["Random", "Test"]
+test = ["Random", "Test", "DrWatson", "SafeTestsets"]

docs/Project.toml

@@ -1,11 +1,10 @@
-# Don't forget to run
-#
-#     pkg> dev ..
-#
 [deps]
 Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
-LiveServer = "16fef848-5104-11e9-1b77-fb7a48bbb589"
 LaserExperiments = "eb1875a3-6e0d-577e-a250-3e610cb08925"
+LiveServer = "16fef848-5104-11e9-1b77-fb7a48bbb589"
+
+[sources]
+LaserExperiments = {path = "/Users/uwe/Work/jlProjects/QEDjl-project/LaserExperiments.jl/docs/.."}
 
 [compat]
 Documenter = "1"

docs/make.jl

@@ -1,36 +1,63 @@
-using LaserExperiments
+using Pkg
+
+# targeting the correct source code
+# this assumes the make.jl script is located in LaserExperiments.jl/docs
+project_path = Base.Filesystem.joinpath(Base.Filesystem.dirname(Base.source_path()), "..")
+Pkg.develop(; path = project_path)
+
 using Documenter
+using LaserExperiments
 
 DocMeta.setdocmeta!(LaserExperiments, :DocTestSetup, :(using LaserExperiments); recursive = true)
 
-const page_rename = Dict("developer.md" => "Developer docs") # Without the numbers
-const numbered_pages = [
-    file for file in readdir(joinpath(@__DIR__, "src")) if
-        file != "index.md" && splitext(file)[2] == ".md"
+# some paths for links
+readme_path = joinpath(project_path, "README.md")
+index_path = joinpath(project_path, "docs/src/index.md")
+license_url = "https://github.com/QEDjl-project/LaserExperiments.jl/blob/main/LICENSE"
+code_of_conduct_url = "https://github.com/QEDjl-project/LaserExperiments.jl/blob/main/CODE_OF_CONDUCT.md"
+
+# Copy README.md from the project base folder and use it as the start page
+open(readme_path, "r") do readme_in
+    readme_string = read(readme_in, String)
+
+    # replace relative links in the README.md
+    readme_string = replace(readme_string, "[MIT](LICENSE)" => "[MIT]($(license_url))")
+    readme_string = replace(readme_string, "(CODE_OF_CONDUCT.md)" => "($(code_of_conduct_url))")
+    readme_string = replace(readme_string, "[contributing guide directly on GitHub](docs/src/90-contributing.md)" => "contributing guide directly on GitHub")
+
+    open(index_path, "w") do readme_out
+        write(readme_out, readme_string)
+    end
+end
+
+pages = [
+    "Home" => "index.md",
+    "Contributing" => "90-contributing.md",
+    "Dev Docs" => "91-developer.md",
+    "References" => "95-reference.md",
 ]
 
-makedocs(;
-    modules = [LaserExperiments],
-    authors = "Uwe Hernandez Acosta <u.hernandez@hzdr.de>",
-    repo = Documenter.Remotes.GitHub("QEDjl-project", "LaserExperiments.jl"),
-    sitename = "LaserExperiments.jl",
-    #format = Documenter.HTML(; canonical = "https://QEDjl-project.github.io/LaserExperiments.jl"),
-    format = Documenter.HTML(;
-        prettyurls = get(ENV, "CI", "false") == "true",
-        canonical = "https://qedjl-project.gitlab.io/LaserExperiments.jl",
-        assets = String[],
-        mathengine = Documenter.MathJax2(),
-        collapselevel = 1,
-        edit_link = :commit,
-        # TODO: workaround
-        # should be fixed: https://github.com/QEDjl-project/QEDbase.jl/issues/4
-        size_threshold_ignore = ["index.md"],
-    ),
-    pages = ["index.md"; numbered_pages],
-)
-
-deploydocs(;
-    devbranch = "main",
-    repo = "github.com/QEDjl-project/LaserExperiments.jl",
-    push_preview = true
-)
+try
+    # generate docs with Documenter.jl
+    makedocs(;
+        modules = [LaserExperiments],
+        checkdocs = :exports,
+        authors = "Uwe Hernandez Acosta",
+        repo = Documenter.Remotes.GitHub("QEDjl-project", "LaserExperiments.jl"),
+        sitename = "LaserExperiments.jl",
+        format = Documenter.HTML(;
+            prettyurls = get(ENV, "CI", "false") == "true",
+            canonical = "https://qedjl-project.gitlab.io/LaserExperiments.jl",
+            assets = String[],
+            mathengine = Documenter.MathJax2(),
+            collapselevel = 1,
+        ),
+        pages = pages,
+    )
+finally
+    # doing some garbage collection
+    @info "GarbageCollection: remove generated landing page"
+    rm(index_path)
+end
+
+deploydocs(; repo = "github.com/QEDjl-project/LaserExperiments.jl.git", push_preview = false)

src/LaserExperiments.jl

@@ -1,20 +1,16 @@
 module LaserExperiments
 
-# this line tests the test coverage
-
-hello_world() = "Hello, World!"
-
 # constants
 export ME_eV
 
 # laser beams
-export LaserBeam, laserbeam
-export classical_nonlinearity_parameter, photon_energy, polar_angle
-export wavelength, unit_wavevector, intensity, frequency, four_momentum
+export LaserParameters, laserparameter
+export classical_nonlinearity_parameter, photon_energy, pulse_duration, pulse_energy, repetition_rate, coherence_length, polarization_ratio
+export wavelength, intensity, frequency, average_power
 
 # electron beam
 export ElectronBeam, electronbeam
-export lorentz_factor, beta, momentum_magnitude, unit_direction, four_momentum, total_energy
+export lorentz_factor, beta, momentum_magnitude, unit_direction, four_momentum, total_energy, polar_angle
 
 using Unitful
 using LinearAlgebra
@@ -27,7 +23,8 @@ include("units.jl")
 include("constants.jl")
 
 include("beams/utils.jl")
-include("beams/laser.jl")
+include("beams/laser/utils.jl")
+include("beams/laser/parameter.jl")
 include("beams/electron.jl")
 
 

src/beams/laser/beam.jl

@@ -0,0 +1,17 @@
+abstract type AbstractBeamProfile end
+
+struct GaussianBeam <: AbstractBeamProfile end
+struct TopHatBeam <: AbstractBeamProfile end
+
+struct BeamParameters{T <: Real}
+    diameter_mm::T                 # 1/e^2 definition
+    power_density_W_cm2::T
+    energy_density_uJ_cm2::T
+    profile::AbstractBeamProfile
+    divergence_mrad::T
+end
+
+struct SystemOpticsParameters{T <: Real}
+    spot_size_um::T
+    working_distance_um::T
+end

src/beams/laser/generic.jl

@@ -0,0 +1,11 @@
+abstract type AbstractLaser end
+
+struct GenericLaser{T <: Real} <: AbstractLaser
+    name::String
+    medium::LaserMedium
+    classification::LaserClassification
+
+    fundamental::FundamentalLaserParameters{T}
+    beam::BeamParameters{T}
+    optics::SystemOpticsParameters{T}
+end

src/beams/laser/laser.jl

@@ -0,0 +1,5 @@
+struct LaserSystem{T <: Real} <: AbstractLaser
+    id::String
+    base::GenericLaser{T}
+    metadata::LaserSystemMetadata
+end

src/beams/laser/medium.jl

@@ -0,0 +1,7 @@
+@enum LaserMedium begin
+    SolidState
+    FEL
+    Gas
+    Liquid
+    Plasma
+end

src/beams/laser/metadata.jl

@@ -0,0 +1,8 @@
+struct LaserSystemMetadata
+    status::LaserStatus
+    institution::String
+    location::String
+    facility::String
+    construction_date::Union{Date, Nothing}
+    last_update::DateTime
+end

src/beams/laser/parameter.jl

@@ -0,0 +1,151 @@
+abstract type AbstractLaserParameters end
+
+struct LaserParameters{T, PhE, PuE, PuD, REP, COH, POL} <: AbstractLaserParameters
+    a0::T
+    photon_energy::PhE
+    pulse_energy::PuE
+    pulse_duration::PuD
+    repetition_rate::REP
+    coherence_length::COH
+    polarization_ratio::POL  # e.g. (1, 100), maybe use irrationals
+
+    function LaserParameters(
+            a0::T,
+            photon_energy::PhE,
+            pulse_energy::PuE,
+            pulse_duration::PuD,
+            repetition_rate::REP,
+            coherence_length::COH,
+            polarization_ratio::POL,
+        ) where {
+            T <: Real,
+            PhE <: Union{Unitful.Energy, Missing},
+            PuE <: Union{Unitful.Energy, Missing},
+            PuD <: Union{Unitful.Time, Missing},
+            REP <: Union{Unitful.Frequency, Missing},
+            COH <: Union{Unitful.Length, Missing},
+            POL <: Union{NTuple{2, T}, Missing},
+        }
+
+        a0 > zero(T) || throw(ArgumentError("`a0` must be non-negative"))
+        ismissing(photon_energy) || ustrip(photon_energy) > zero(T) || throw(ArgumentError("photon energy must be positive"))
+        ismissing(pulse_energy) || ustrip(pulse_energy) > zero(T) || throw(ArgumentError("pulse energy must be positive"))
+        ismissing(pulse_duration) || ustrip(pulse_duration) > zero(T) || throw(ArgumentError("pulse duration must be positive"))
+        ismissing(repetition_rate) || ustrip(repetition_rate) > zero(T) || throw(ArgumentError("repetition rate must be positive"))
+        ismissing(coherence_length) || ustrip(coherence_length) > zero(T) || throw(ArgumentError("coherence length must be positive"))
+        ismissing(polarization_ratio) || all(p -> p > zero(T), polarization_ratio) ||
+            throw(ArgumentError("polarization ratio entries must be positive"))
+
+        return new{T, PhE, PuE, PuD, REP, COH, POL}(
+            a0,
+            photon_energy,
+            pulse_energy,
+            pulse_duration,
+            repetition_rate,
+            coherence_length,
+            polarization_ratio
+        )
+    end
+end
+
+classical_nonlinearity_parameter(L::LaserParameters) = L.a0
+photon_energy(L::LaserParameters) = L.photon_energy
+pulse_energy(L::LaserParameters) = L.pulse_energy
+pulse_duration(L::LaserParameters) = L.pulse_duration
+repetition_rate(L::LaserParameters) = L.repetition_rate
+coherence_length(L::LaserParameters) = L.coherence_length
+polarization_ratio(L::LaserParameters) = L.polarization_ratio
+
+
+function _infer_a0(a0, intensity, omega)
+    if a0 === nothing
+        intensity === nothing && throw(
+            ArgumentError(
+                "`a0` or `intensity` must be specified"
+            )
+        )
+        a0 = _compute_a0_from_omega(intensity, omega)
+    end
+    return a0
+end
+
+function _infer_photon_energy(omega, wavelength, frequency)
+    if omega === nothing
+        if wavelength !== nothing
+            omega = Unitful.h * Unitful.c0 / wavelength
+        elseif frequency !== nothing
+            omega = Unitful.h * frequency
+        else
+            throw(
+                ArgumentError(
+                    "`photon_energy`, `omega`, `wavelength` or `frequency` must be specified"
+                )
+            )
+
+        end
+    end
+    return omega |> u"eV"
+end
+
+function _infer_pulse_energy(pulse_energy, average_power, repetition_rate)
+    if pulse_energy === nothing
+        average_power === nothing && (return missing)
+        repetition_rate === nothing && throw(
+            ArgumentError(
+                "if `average_power` is given, `repetition_rate` must be specified as well"
+            )
+        )
+        pulse_energy = average_power / repetition_rate
+    end
+    return ismissing(pulse_energy) ? pulse_energy : pulse_energy |> u"J"
+end
+
+function laserparameter(;
+        a0 = nothing,
+        intensity = nothing,
+
+        wavelength = nothing,
+        frequency = nothing,
+        photon_energy = nothing,
+        omega = photon_energy,
+
+        pulse_duration = nothing,
+        coherence_length = nothing,
+        polarization_ratio = nothing,
+
+        pulse_energy = nothing,
+        average_power = nothing,
+        repetition_rate = nothing,
+    )
+
+    # --- infer photon energy ---
+    omega = _infer_photon_energy(omega, wavelength, frequency)
+
+    # --- infer a0 ---
+    a0 = _infer_a0(a0, intensity, omega)
+
+
+    #pulse_energy = pulse_energy === nothing || ismissing(pulse_energy) ? missing : pulse_energy|> u"J"
+    pulse_duration = pulse_duration === nothing || ismissing(pulse_duration) ? missing : pulse_duration |> u"fs"
+    repetition_rate = repetition_rate === nothing || ismissing(repetition_rate) ? missing : repetition_rate |> u"Hz"
+    coherence_length = coherence_length === nothing || ismissing(coherence_length) ? missing : coherence_length |> u"cm"
+
+    # -- infer pulse_energy --
+    pulse_energy = _infer_pulse_energy(pulse_energy, average_power, repetition_rate)
+
+    polarization_ratio = isnothing(polarization_ratio) ? missing : polarization_ratio
+    return LaserParameters(
+        a0,
+        omega,
+        pulse_energy,
+        pulse_duration,
+        repetition_rate,
+        coherence_length,
+        polarization_ratio
+    )
+end
+
+intensity(l::LaserParameters) = _compute_intensity_from_omega(l.a0, l.photon_energy)
+frequency(l::LaserParameters) = l.photon_energy / Unitful.h |> u"Hz"
+wavelength(l::LaserParameters) = Unitful.h * Unitful.c0 / l.photon_energy |> u"µm"
+average_power(l::LaserParameters) = l.pulse_energy * l.repetition_rate

src/beams/laser/status.jl

@@ -0,0 +1,7 @@
+@enum LaserStatus begin
+    Commissioned
+    Operating
+    Construction
+    Design
+    Decommissioned
+end