Merge pull request #165 from lmh91/docs

Update Documentation

docs/.gitignore

@@ -2,4 +2,5 @@ build/
 site/
 src/ssd_tutorial.ipynb
 src/ssd_tutorial.jl
-src/tutorial.md
+src/tutorial.md
+src/man/primitives.md

docs/make.jl

@@ -16,12 +16,16 @@ function fix_literate_output(content)
     return content
 end
 
-# gen_content_dir = joinpath(@__DIR__, "src")
-# tutorial_src = joinpath(@__DIR__, "src", "tutorial_lit.jl")
-# Literate.markdown(tutorial_src, gen_content_dir, name = "tutorial", documenter = true, credit = true, postprocess = fix_literate_output)
-# #Literate.markdown(tutorial_src, gen_content_dir, name = "tutorial", codefence = "```@repl tutorial" => "```", documenter = true, credit = true)
-# Literate.notebook(tutorial_src, gen_content_dir, execute = false, name = "ssd_tutorial", documenter = true, credit = true)
-# Literate.script(tutorial_src, gen_content_dir, keep_comments = false, name = "ssd_tutorial", documenter = true, credit = false)
+gen_content_dir = joinpath(@__DIR__, "src")
+tutorial_src = joinpath(@__DIR__, "src", "tutorial_lit.jl")
+Literate.markdown(tutorial_src, gen_content_dir, name = "tutorial", documenter = true, credit = true, postprocess = fix_literate_output)
+#Literate.markdown(tutorial_src, gen_content_dir, name = "tutorial", codefence = "```@repl tutorial" => "```", documenter = true, credit = true)
+Literate.notebook(tutorial_src, gen_content_dir, execute = false, name = "ssd_tutorial", documenter = true, credit = true)
+Literate.script(tutorial_src, gen_content_dir, keep_comments = false, name = "ssd_tutorial", documenter = true, credit = false)
+
+gen_content_dir = joinpath(@__DIR__, "src", "man")
+primitives_src = joinpath(@__DIR__, "src", "man", "primitives.jl")
+Literate.markdown(primitives_src, gen_content_dir, name = "primitives", documenter = true, credit = true, postprocess = fix_literate_output)
 
 
 makedocs(
@@ -44,7 +48,7 @@ makedocs(
             "Drift Fields" => "man/drift_fields.md",
             "IO" => "man/IO.md",
         ],
-        # "Tutorial" => "tutorial.md",
+        "Tutorial" => "tutorial.md",
         "API" => "api.md",
         "LICENSE" => "LICENSE.md",
     ],

docs/src/man/primitives.jl

@@ -0,0 +1,70 @@
+# ## Volume Primitives
+
+using SolidStateDetectors
+import SolidStateDetectors.ConstructiveSolidGeometry as CSG
+using SolidStateDetectors.ConstructiveSolidGeometry: ClosedPrimitive
+using SolidStateDetectors.ConstructiveSolidGeometry: Box
+using Plots
+T = Float64;
+
+# ### List of YAML example configuration files for Primitives
+# Under `SolidStateDetectors.jl/examples/example_primitive_files` there 
+# are some examples how to define the different primitives 
+# via the YAML format:
+
+path_to_example_primitives_config_files = joinpath(dirname(dirname(pathof(SolidStateDetectors))), "examples", "example_primitive_files") 
+example_primitives_config_filenames = readdir(path_to_example_primitives_config_files) 
+for fn in example_primitives_config_filenames
+    println(fn)
+end
+
+# ### Box
+cfn = joinpath(path_to_example_primitives_config_files, "Box.yaml")
+print(open(f -> read(f, String), cfn))
+
+# Load the primitive from the configuration file via `CSG.Geometry`
+box = CSG.Geometry(T, cfn)
+plot(box)
+
+# ### Cone:
+# #### Tube
+cfn = joinpath(path_to_example_primitives_config_files, "Tube.yaml")
+print(open(f -> read(f, String), cfn))
+
+# Load the primitive from the configuration file via `CSG.Geometry`
+cone = CSG.Geometry(T, cfn)
+plot(cone)
+
+# #### VaryingTube
+cfn = joinpath(path_to_example_primitives_config_files, "Cone.yaml")
+print(open(f -> read(f, String), cfn))
+
+# Load the primitive from the configuration file via `CSG.Geometry`
+cone = CSG.Geometry(T, cfn)
+plot(cone)
+
+# ### Ellipsoid
+# #### Sphere
+cfn = joinpath(path_to_example_primitives_config_files, "Sphere.yaml")
+print(open(f -> read(f, String), cfn))
+
+# Load the primitive from the configuration file via `CSG.Geometry`
+ellipsoid = CSG.Geometry(T, cfn)
+plot(ellipsoid)
+
+# ### Torus
+cfn = joinpath(path_to_example_primitives_config_files, "Torus.yaml")
+print(open(f -> read(f, String), cfn))
+
+# Load the primitive from the configuration file via `CSG.Geometry`
+torus = CSG.Geometry(T, cfn)
+plot(torus, zlims = [-6,6], camera = (40, 55))
+
+# ### Prism
+# #### Hexagonal Prism
+cfn = joinpath(path_to_example_primitives_config_files, "HexagonalPrism.yaml")
+print(open(f -> read(f, String), cfn))
+
+# Load the primitive from the configuration file via `CSG.Geometry`
+prism = CSG.Geometry(T, cfn)
+plot(prism)

docs/src/tutorial_lit.jl

@@ -50,7 +50,7 @@ get_active_volume(simulation.point_types) # approximation (sum of the volume of
 # SolidStateDetectors.jl can also calculate the electric potential of a partially depleted detector:
 
 simulation_undep = deepcopy(simulation)
-simulation_undep.detector.contacts[end].potential = 500; # V  <-- Bias Voltage of Mantle
+simulation_undep.detector = SolidStateDetector(simulation_undep.detector, contact_id = 2, contact_potential = 500); # V  <-- Bias Voltage of Mantle
 
 calculate_electric_potential!( simulation_undep,
                                depletion_handling = true,
@@ -91,7 +91,7 @@ plot(simulation.electric_field, φ = 0.0, size = (350, 500))
 # Set the charge drift model of the simulation:
 
 charge_drift_model = ADLChargeDriftModel()
-set_charge_drift_model!(simulation, charge_drift_model)
+simulation.detector = SolidStateDetector(simulation.detector, charge_drift_model)
 
 
 # And apply the charge drift model to the electric field:

examples/example_primitive_files/Torus.yaml

@@ -4,9 +4,9 @@ torus:
       from: 2.0
       to: 2.0
   phi: 
-      from: 0.0
-      to: 360.0
+      from: 0.0°
+      to: 360.0°
   theta: 
-      from: 0.0
-      to: 360.0
+      from: 0.0°
+      to: 360.0°
   z: 0.0

src/ConstructiveSolidGeometry/ConstructiveSolidGeometry.jl

@@ -8,6 +8,7 @@ module ConstructiveSolidGeometry
 
     # # Other Packages
     using IntervalSets
+    using JSON
     using Parameters
     using PolygonOps
     using Polynomials
@@ -16,6 +17,7 @@ module ConstructiveSolidGeometry
     using StaticArrays
     using Statistics
     using Unitful
+    using YAML
 
     using DataStructures: OrderedDict
 

src/ConstructiveSolidGeometry/IO.jl

@@ -83,7 +83,8 @@ function _parse_angular_interval(::Type{T}, dict::AbstractDict, unit::Unitful.Un
     φFrom::T = _parse_value(T, dict["from"], unit)
     if abs(rem2pi(φFrom - φTo, RoundNearest)) > 2*eps(T)
         φFrom, φTo
-        #else nothing 
+    else 
+        nothing 
     end
 end
 
@@ -262,6 +263,18 @@ function Geometry(::Type{T}, dict::AbstractDict, input_units::NamedTuple, outer_
     Geometry(T, CSG_dict[key], dict[key], input_units, transformations)
 end
 
+function Geometry(::Type{T}, filename::String, input_units::NamedTuple = (length = internal_unit_length, angle = internal_unit_angle)) where {T}
+    @assert isfile(filename) "The given filename '$(filename)' does not lead to a valid file."
+    dict = if endswith(filename, ".json")
+        JSON.parsefile(filename)
+    elseif endswith(filename, ".yaml")
+        YAML.load_file(filename)
+    else
+        @error "Only JSON and YAML formats are supported at the moment."
+    end
+    transformation = (rotation = one(SMatrix{3, 3, T, 9}), translation = zero(CartesianVector{T}))
+    Geometry(T, dict, input_units, transformation)
+end
 
 function show_CSG_tree(csgtree; start = "", tab = "", CSG = false)
     CT = typeof(csgtree)

src/ConstructiveSolidGeometry/LinePrimitives/Edge.jl

@@ -25,4 +25,11 @@ function sample(e::Edge{T}; n = 2)::Vector{CartesianPoint{T}} where {T}
         pts[i] = e.a + xs[i] .* dir
     end
     pts
+end
+function sample(es::Vector{Edge{T}}; n = 2)::Vector{CartesianPoint{T}} where {T}
+    pts = Vector{CartesianPoint{T}}(undef, length(es) * n)
+    for i in eachindex(es)
+        pts[i:i+n-1] = sample(es[i], n = n)
+    end
+    pts
 end