Remove QuantumControlBase

Author: goerz

Project.toml

@@ -8,8 +8,9 @@ FileIO = "5789e2e9-d7fb-5bc7-8068-2c6fae9b9549"
 IOCapture = "b5f81e59-6552-4d32-b1f0-c071b021bf89"
 JLD2 = "033835bb-8acc-5ee8-8aae-3f567f8a3819"
 LinearAlgebra = "37e2e46d-f89d-539d-b4ee-838fcccc9c8e"
+Logging = "56ddb016-857b-54e1-b83d-db4d58db5568"
 Pkg = "44cfe95a-1eb2-52ea-b672-e2afdf69b78f"
-QuantumControlBase = "f10a33bc-5a64-497c-be7b-6f86b4f0c2aa"
+Printf = "de0858da-6303-5e67-8744-51eddeeeb8d7"
 QuantumPropagators = "7bf12567-5742-4b91-a078-644e72a65fc1"
 UUIDs = "cf7118a7-6976-5b1a-9a39-7adc72f591a4"
 
@@ -26,7 +27,9 @@ FileIO = "1"
 FiniteDifferences = "0.12"
 IOCapture = "0.2.4"
 JLD2 = "0.4"
-QuantumControlBase = ">=0.10.0"
+LinearAlgebra = "1"
+Logging = "1"
+Printf = "1"
 QuantumPropagators = ">=0.8.0"
 Zygote = "0.6"
 julia = "1.9"

docs/generate_api.jl

@@ -59,22 +59,23 @@ end
 
 quantum_control_members = [
     m for m in names(QuantumControl)
-    if m ≠ :QuantumControl
+    if  (m ≠ :QuantumControl) && (m ∉ QuantumControl.DEPRECATED)
 ]
 
-quantum_control_local_members = get_local_members(QuantumControl, all=false)
+quantum_control_local_members = filter(
+    member -> member ∉ QuantumControl.DEPRECATED,
+    get_local_members(QuantumControl, all=false)
+)
 
 quantum_control_reexported_members = [
-    m for m in quantum_control_members
-    if m ∉ quantum_control_local_members
+    m for m in quantum_control_members if m ∉ quantum_control_local_members
 ]
 
 quantum_control_sub_modules = get_submodules(QuantumControl)
 
 
 subpackages = [
     (:QuantumPropagators, "quantum_propagators.md"),
-    (:QuantumControlBase, "quantum_control_base.md"),
 ]
 
 
@@ -84,20 +85,27 @@ open(outfile, "w") do out
     write(out, "```@meta\n")
     write(out, "EditURL = \"../../generate_api.jl\"\n")
     write(out, "```\n\n")
-    write(out, "# [QuantumControl](@id QuantumControlAPI)\n\n")
-    _quantum_control_local_members  = filter(
-        member -> !(member in QuantumControl.DEPRECATED),
-        quantum_control_local_members
-    )
-    if length(_quantum_control_local_members) > 0
-        error("QuantumControl has local members. We don't want this")
-    end
+    write(out, "# [QuantumControl Public API](@id QuantumControlAPI)\n\n")
     write(out, """
+    This page summarizes the public API of the `QuantumControl` package. See
+    also the [Index](@ref API-Index) of *all* symbols.
+
+    QuantumControl exports the following symbols:
 
-    QuantumControl (re-)exports the following symbols:
+    """)
+    for name ∈ quantum_control_local_members
+        obj = getfield(QuantumControl, name)
+        ref = canonical_name(obj)
+        println(out, "* [`$name`](@ref $ref)")
+    end
 
+    write(out, """
 
+    and re-exports the following symbols either from its own
+    [submodules](@ref public_submodules) or from
+    [`QuantumPropagators`](@ref QuantumPropagatorsPackage):
     """)
+
     for name ∈ quantum_control_reexported_members
         obj = getfield(QuantumControl, name)
         ref = canonical_name(obj)
@@ -106,13 +114,24 @@ open(outfile, "w") do out
 
     write(out, """
 
-    It also defines the following unexported functions:
+    It also defines the following public, but unexported functions:
 
     * [`QuantumControl.set_default_ad_framework`](@ref)
-    * [`QuantumControl.print_versions`](@ref)
 
     """)
 
+    write(out, """
+    ### [Submodules](@id public_submodules)
+
+    Each of the following submodules defines their own public API. Note that
+    some of these submodules are re-exported from or extend submodules of
+    [`QuantumPropagators`](@ref QuantumPropagatorsPackage).
+
+    """)
+    for submod in quantum_control_sub_modules
+        write(out, "* [`QuantumControl.$(submod)`](@ref QuantumControl$(submod)API)\n")
+    end
+
     for submod in quantum_control_sub_modules
         write(out, "\n\n### [`QuantumControl.$submod`](@id QuantumControl$(submod)API)\n\n")
         for name in names(getfield(QuantumControl, submod))
@@ -140,8 +159,6 @@ open(outfile, "w") do out
 end
 
 
-local_submodules = [:Functionals, :PulseParameterizations, :Workflows]
-
 local_module_api_id(mod) = replace("$mod", "." => "") * "LocalAPI"
 
 function write_module_api(out, mod, description="")
@@ -178,14 +195,14 @@ function write_module_api(out, mod, description="")
         write(out, "\n\n")
     end
     if length(public_members) > 0
-        write(out, "\nPublic Members:\n\n")
+        write(out, "\nPublic Symbols:\n\n")
         for name ∈ public_members
             println(out, "* [`$name`](@ref $mod.$name)")
         end
         write(out, "\n")
     end
     if length(reexported_members) > 0
-        write(out, "\nRe-exported Members:\n\n")
+        write(out, "\nRe-exported Symbols:\n\n")
         for name ∈ reexported_members
             obj = getfield(mod, name)
             ref = canonical_name(obj)
@@ -194,22 +211,22 @@ function write_module_api(out, mod, description="")
         write(out, "\n")
     end
     if length(documented_private_members) > 0
-        write(out, "\nPrivate Members:\n")
+        write(out, "\nPrivate Symbols:\n")
         for name ∈ documented_private_members
             println(out, "* [`$name`](@ref $mod.$name)")
         end
         write(out, "\n")
     end
     if length(public_members) > 0
-        write(out, "\n\n#### Public members\n\n")
+        write(out, "\n\n#### Public Symbols\n\n")
         println(out, "```@docs")
         for name ∈ public_members
             println(out, "$mod.$name")
         end
         println(out, "```")
     end
     if length(documented_private_members) > 0
-        write(out, "\n\n#### Private members\n\n")
+        write(out, "\n\n#### Private Symbols\n\n")
         println(out, "```@docs")
         for name ∈ documented_private_members
             println(out, "$mod.$name")
@@ -220,52 +237,67 @@ function write_module_api(out, mod, description="")
 end
 
 
-outfile = joinpath(@__DIR__, "src", "api", "quantum_control_reference.md")
+outfile = joinpath(@__DIR__, "src", "api", "reference.md")
 println("Generating local reference for QuantumControl in $outfile")
 open(outfile, "w") do out
     write(out, "```@meta\n")
     write(out, "EditURL = \"../../generate_api.jl\"\n")
     write(out, "```\n\n")
     write(out, raw"""
-    # Local Submodules
+    # API Reference
 
-    The following submodules of `QuantumControl` are defined *locally* (as
-    opposed to being re-exported from sub-packages).
+    This page provides *all* docstrings locally defined in the `QuantumControl`
+    package for both private and public symbols. See also the summary of the
+    [public API](@ref QuantumControlAPI).
 
-    ``\gdef\tgt{\text{tgt}}``
-    ``\gdef\tr{\operatorname{tr}}``
-    ``\gdef\Re{\operatorname{Re}}``
-    ``\gdef\Im{\operatorname{Im}}``
-    """)
-    for name in local_submodules
-        write(out, "* [`QuantumControl.$name`](#$(local_module_api_id(getfield(QuantumControl, name))))\n")
-    end
-    write(out, raw"""
+    `QuantumControl` exposes local [exported](#quantumcontrol-local-symbols)
+    and [unexported](#quantumcontrol-local-unexported-symbols) local symbols as
+    well as re-exporting symbols and sub-modules from the
+    [QuantumPropagators](@ref QuantumPropagatorsPackage) subpackage and some
+    of its submodules.
 
-    `QuantumControl` also locally defines some unexported functions:
+    The [`QuantumControl` submodules](@ref quantumcontrol-submodules) provide
+    additional public functionality. Note that some of the most commonly
+    used symbols from `QuantumControl`'s submodules may also be re-exported at
+    the top-level (such as [`@optimize_or_load`](@ref) from the
+    [`QuantumControl.Workflows`](@ref QuantumControlWorkflowsAPI) submodule).
 
-    * [`QuantumControl` local unexported functions](#quantumcontrol-local-functions)
+    """)
+    write(out, raw"""
 
+    ## [Local Exported Symbols](@id #quantumcontrol-local-symbols)
 
     """)
-    for name in local_submodules
-        write_module_api(out, getfield(QuantumControl, name))
+    println(out, "```@docs")
+    for name ∈ quantum_control_local_members
+        println(out, "QuantumControl.$name")
     end
+    println(out, "```")
     write(out, raw"""
 
-    ## [`QuantumControl` local unexported functions](@id quantumcontrol-local-functions)
+    ## [Local Unexported Symbols](@id quantumcontrol-local-unexported-symbols)
 
     ```@docs
     QuantumControl.set_default_ad_framework
-    QuantumControl.print_versions
     ```
+    """)
+    write(out, raw"""
+    ``\gdef\tgt{\text{tgt}}``
+    ``\gdef\tr{\operatorname{tr}}``
+    ``\gdef\Re{\operatorname{Re}}``
+    ``\gdef\Im{\operatorname{Im}}``
 
-    ```@example
-    import QuantumControl
-    QuantumControl.print_versions()
-    ```
+    ## [List of Submodules](@id quantumcontrol-submodules)
+
+    `QuantumControl` has the following sub-modules:
 
     """)
+    for name in quantum_control_sub_modules
+        write(out, "* [`QuantumControl.$name`](#$(local_module_api_id(getfield(QuantumControl, name))))\n")
+    end
+    for name in quantum_control_sub_modules
+        write_module_api(out, getfield(QuantumControl, name))
+    end
 end
 
 
@@ -276,7 +308,7 @@ open(outfile, "w") do out
     write(out, "EditURL = \"../../generate_api.jl\"\n")
     write(out, "```\n\n")
     write(out, raw"""
-    # API Index
+    # [API Index](@id API-Index)
 
     ```@index
     ```
@@ -320,13 +352,13 @@ for (pkgname::Symbol, outfilename) in subpackages
         """)
         write(out, "\n\n## [`$pkgname`](@id $(pkgname)API)\n\n")
         if length(public_members) > 0
-            write(out, "\nPublic Members:\n\n")
+            write(out, "\nPublic Symbols:\n\n")
             for name in public_members
                 write(out, "* [`$name`](@ref $pkgname.$name)\n")
             end
         end
         if length(documented_private_members) > 0
-            write(out, "\nPrivate Members:\n\n")
+            write(out, "\nPrivate Symbols:\n\n")
             for name in documented_private_members
                 write(out, "* [`$name`](@ref $pkgname.$name)\n")
             end

docs/make.jl

@@ -2,7 +2,6 @@ using Pkg
 
 using Documenter
 using QuantumPropagators
-using QuantumControlBase
 using QuantumControl
 using QuantumControl.Shapes
 using QuantumControl.Functionals
@@ -25,6 +24,16 @@ if endswith(VERSION, "dev")
     DEV_OR_STABLE = "dev/"
 end
 
+function org_inv(pkgname)
+    objects_inv =
+        joinpath(@__DIR__, "..", "..", "$pkgname.jl", "docs", "build", "objects.inv")
+    if isfile(objects_inv)
+        return ("https://juliaquantumcontrol.github.io/$pkgname.jl/dev/", objects_inv,)
+    else
+        return "https://juliaquantumcontrol.github.io/$pkgname.jl/$DEV_OR_STABLE"
+    end
+end
+
 links = InterLinks(
     "Julia" => (
         "https://docs.julialang.org/en/v1/",
@@ -36,10 +45,10 @@ links = InterLinks(
         joinpath(@__DIR__, "src", "inventories", "TimerOutputs.toml")
     ),
     "Examples" => "https://juliaquantumcontrol.github.io/QuantumControlExamples.jl/$DEV_OR_STABLE",
-    "Krotov" => "https://juliaquantumcontrol.github.io/Krotov.jl/$DEV_OR_STABLE",
-    "GRAPE" => "https://juliaquantumcontrol.github.io/GRAPE.jl/$DEV_OR_STABLE",
-    "QuantumPropagators" => "https://juliaquantumcontrol.github.io/QuantumPropagators.jl/$DEV_OR_STABLE",
-    "QuantumGradientGenerators" => "https://juliaquantumcontrol.github.io/QuantumGradientGenerators.jl/$DEV_OR_STABLE",
+    "Krotov" => org_inv("Krotov"),
+    "GRAPE" => org_inv("GRAPE"),
+    "QuantumPropagators" => org_inv("QuantumPropagators"),
+    "QuantumGradientGenerators" => org_inv("QuantumGradientGenerators"),
     "ComponentArrays" => (
         "https://jonniedie.github.io/ComponentArrays.jl/stable/",
         "https://jonniedie.github.io/ComponentArrays.jl/stable/objects.inv",
@@ -84,7 +93,8 @@ makedocs(;
                 "https://juliaquantumcontrol.github.io/QuantumControl.jl/dev/assets/topbar/topbar.js"
             ),
         ],
-        footer="[$NAME.jl]($GITHUB) v$VERSION docs powered by [Documenter.jl](https://github.com/JuliaDocs/Documenter.jl)."
+        footer="[$NAME.jl]($GITHUB) v$VERSION docs powered by [Documenter.jl](https://github.com/JuliaDocs/Documenter.jl).",
+        size_threshold=1024 * 1024,
     ),
     pages=[
         "Home" => "index.md",
@@ -95,11 +105,8 @@ makedocs(;
         "Examples" => "examples/index.md",
         "API" => [
             "QuantumControl" => "api/quantum_control.md",
-            "Local Submodules" => "api/quantum_control_reference.md",
-            "Subpackages" => [
-                "QuantumPropagators" => "api/quantum_propagators.md",
-                "QuantumControlBase" => "api/quantum_control_base.md",
-            ],
+            "Reference" => "api/reference.md",
+            "Subpackages" => ["QuantumPropagators" => "api/quantum_propagators.md",],
             "Externals" => "api_externals.md",
             "Index" => "api/quantum_control_index.md",
         ],

docs/src/assets/topbar/topbar.js

@@ -18,7 +18,6 @@ document.addEventListener("DOMContentLoaded", function() {
     }
     var packages = [
         "QuantumPropagators.jl",
-        "QuantumControlBase.jl",
         "QuantumGradientGenerators.jl",
         "ParameterizedQuantumControl.jl",
         "Krotov.jl",

docs/src/index.md

@@ -62,9 +62,6 @@ Depth = 1
 ```@contents
 Pages = [
     "api/quantum_propagators.md",
-    "api/quantum_control_base.md",
-    "api/krotov.md",
-    "api/grape.md",
 ]
 Depth = 1
 ```