documentation big time

docs/build/.documenter-siteinfo.json

@@ -1 +1 @@
-{"documenter":{"julia_version":"1.9.4","generation_timestamp":"2024-06-09T21:23:48","documenter_version":"1.4.1"}}
+{"documenter":{"julia_version":"1.9.4","generation_timestamp":"2024-09-14T23:16:58","documenter_version":"1.6.0"}}

docs/build/objects.inv

@@ -2,5 +2,7 @@
 # Project: ShockwaveDetection.jl Documentation
 # Version: 1.0.0-DEV
 # The remainder of this file is compressed using zlib.
-x����
-�0E����n+��Z����aL�tj%��~�&nZ(���{9���$�1A����58�ZBI��B,>�fv8��j�����������W��y!�2p�Vf��~�Hh $�@ǖ�`��k��k������,,=L9����n�3E
	0Fv,<�7��C�-��c��
+x��TMo�0��WX��{�d�aA��
+�D;jeɐ��ٯ��|4����E�-���G��*�!��WN��õX�l�y4�P�@>J
+LX��h%igC
�M�}��
�H8c��:Da�_�_?��]������I�=�UԏQ�E��pV-�ՄL�F�V��z�`����� ���Ě������9Cz��uB����4^+�	�ӴI	�hC�nݳ�����Q:�
+=$�=��D����&�C��LgzX���z��M��FOޡ�;!_HX�>������N�2W_:6�f�0��Ҍ4
D�67�}��R���fy\��ҧ��b�Nl��U���ܟ��z��i��o�ي�����er�m�#V��fb�ݢ'N�w^����B��1[ʭ�0|�.���^�[�N������8:�kM���1��3�ߞ��q3Ē�QKv�v����}]�Ж�-,�������g��ڴ!O�I!M�0���O���������6m����pS

docs/src/index.md

@@ -1,23 +1,70 @@
 # ShockDetection.jl
 
 ShockDetection.jl is a Julia package for detecting shocks in time series data from Godunov solver.
+The packages can detect shock discontinuities for grid data with dimensions
+- Nx x Nt when Nx are the number of grid points in x axis and Nt is the number of time steps in the simulation
+- Nx x Ny x Nt when Nx and Ny are the number of grid points in x and y axes respectively, and Nt is the number of time steps in the simulation
+
+The package can only process simulation files that end with .tape and .celltape. Other simulation file types are not supported!
 
 ## Features
 
-- A method for shock detection.
-- Easy-to-use functions for analyzing time series data.
-- Compatible with Julia 1.9.
+- A method for shock detection. The gradient of each point in the simulation is calculated using finite difference method, clustered by DBSCAN algorithm and optimal shock curves are fitted using Levenberg–Marquardt algorithm.
+- Visualization is also available within the package. You can also automatically calculate the normal vectors of 2D simulation as you call the function `create_heatmap_evo_with_shock`. But if you wish to obtain the normal vector of each curve in a specified time frame, the function `calculate_normal_vector` is also available for you.
+- Compatible with Julia 1.9 and 1.10.
 
 ## Installation
 
 You can install ShockDetection.jl using the Julia package manager. From the Julia REPL, type `]` to enter the Pkg REPL mode
+There are several dependencies needed to run this pacakge. Checkout `Project.toml` to see what packages you need to have in order to run `ShockwaveDetection.jl`
+
+## Guide
+
+Go to our examples directory to see how to use our functions!
+
+### Short guide on how to use our package on grid data with dimension Nx x Ny x Nt
+When you wish to use our package to detect shock discontinuities,  you should first input your data file path into `FlowData`.
+After that, define your algorithm of finite difference, clustering, and fitting that best suited your simulation data and use
+the function `detect` to automate the process the detection process. The results of your detection can be found in `ShockDetectionResult2D`. You can further use various functions in visualization to
+see the result.
 
-# Functions
+# Functions and structs
 
+## Main functions and structs of our package
+These are the most important functions and structs in our package. Others are functions/structs called/used/stored by `detect`/ `ShockDetectionResult2D` to perform shock detections but they still exist in this documentation to clarify to you how our algorithm works!
+```@docs
+detect
+ShockDetectionResult2D
+```
+
+## Input-related structs and functions
 ```@docs
-read_output_file
 convert_to_primitive
-detect_normal_shock
+FlowData
+```
+
+## Finite difference-related functions and structs
+```@docs
+ImageProcessingShockDetectionAlgo
+```
+
+## Cluster-related functions and structs
+```@docs
+cartesian_index_to_xy
+cluster_shock_points
+DBSCANAlgo
+```
+
+## Fitting-related functions and structs
+```@docs
+fit_shock_clusters_over_time
+calculate_normal_vector
+```
+
+## Visualization functions
+```@docs
+create_heatmap_evo_with_shock
 create_wave_animation
 create_wave_animation_with_shock
+plot_shock_fits_over_time
 ```

src/ShockwaveDetection.jl

@@ -18,7 +18,6 @@ include("input.jl")
 include("variable_utils.jl")
 include("shock_point_detectors/1D/shock_algorithms_1D.jl") # Maybe write one files that includes all the files in the shock_detectors folder?
 include("shock_point_detectors/2D/shock_algorithms_2D.jl")
-include("shock_analysis/normal_shock_analysis.jl")
 include("cluster.jl")
 include("fitting.jl")
 include("visualize.jl")

src/cluster.jl

@@ -1,6 +1,22 @@
 using Clustering
 
-# a struct that keeps all the necessary parameters for the dbscan_algo algorithm
+"""
+    struct DBSCANAlgo
+
+A structure that keeps all the necessary parameters for the DBSCAN clustering algorithm.
+
+# Fields
+- `radius::Float64`: The radius within which to search for neighboring points.
+- `min_neighbors::Int`: The minimum number of neighbors required to form a dense region.
+- `min_cluster_size::Int`: The minimum number of points required to form a cluster.
+
+# Constructors
+- `DBSCANAlgo(radius::Float64 = 0.5, min_neighbors::Int = 3, min_cluster_size::Int = 10)`: 
+  Creates a new `DBSCANAlgo` instance with the specified parameters. Default values are provided for all parameters.
+
+# Example
+algo = DBSCANAlgo(radius=1.0, min_neighbors=5, min_cluster_size=15)
+"""
 struct DBSCANAlgo
     radius::Float64
     min_neighbors::Int

src/fitting.jl

@@ -169,7 +169,7 @@ Calculate the normal vector to a fitted line model at a specific time step in th
 
 # Description
 This function calculates the normal vector to a fitted line model at a specific time step in the flow data. It first extracts the density field at the given time step and retrieves the number of cells and bounds from the flow data. If the model is a line model, it calculates the slope (`m`) and intercept (`b`) from the fit parameters. The magnitude of the normal vector is computed, and the x and y components of the normal vector are determined. The function then finds the midpoint of the line and its corresponding indices in the x and y directions. Finally, it calculates the coordinate movements based on the slope.
-This function is called within the `create_wave_animation_with_shock` function to calculate the normal vectors for the fitted shock models.
+This function is called within the `create_heatmap_evo_with_shock` function to calculate the normal vectors for the fitted shock models.
 """
 function calculate_normal_vector(fit::Fitting, evenly_spaced_range, flow_data, t)
     density_field_t = flow_data.density_field[:,:,t]

src/input.jl

@@ -4,7 +4,23 @@ using LinearAlgebra
 using ShockwaveProperties
 using Unitful
 
+"""
+    struct FlowData{N, T}
 
+A structure to hold flow data for simulations.
+
+# Fields
+- `ncells::NTuple{N, Int}`: Number of cells in each dimension.
+- `nsteps::Int`: Number of time steps in the simulation.
+- `bounds::NTuple{N, Tuple{T, T}}`: Bounds of the simulation domain in each dimension.
+- `tsteps::Vector{T}`: Time steps of the simulation.
+- `u::Union{Array{T}, Nothing}`: Array of primitive variables or `Nothing` for `.celltape` data.
+- `density_field::Array{T}`: Density field of the simulation.
+- `velocity_field::Array{T}`: Velocity field of the simulation.
+- `pressure_field::Array{T}`: Pressure field of the simulation.
+- `mach_to_m_s::Bool`: Flag indicating if Mach number should be converted to meters per second.
+- `cell_ids::Union{Matrix{Int64}, Nothing}`: Cell IDs for `.celltape` data. `Nothing` for `.tape` data.
+"""
 struct FlowData{N, T}
     ncells::NTuple{N, Int}
     nsteps::Int
@@ -18,7 +34,21 @@ struct FlowData{N, T}
     cell_ids::Union{Matrix{Int64}, Nothing}
 end
 
+"""
+    FlowData(file_path::String, mach_to_m_s=true)
+
+Load flow data from a file and create a `FlowData` object.
+
+# Arguments
+- `file_path::String`: Path to the file containing the simulation data.
+- `mach_to_m_s::Bool=true`: Flag indicating if Mach number should be converted to meters per second.
+
+# Returns
+- `FlowData`: A `FlowData` object containing the loaded simulation data.
 
+# Description
+This function loads flow data from a specified file path. It supports both `.tape` and `.celltape` file formats. For `.tape` files, it loads Euler simulation data and converts it to primitive variables. For `.celltape` files, it loads cell simulation data.
+"""
 function FlowData(file_path::String, mach_to_m_s=true)
     if endswith(file_path, ".tape")
         sim_data = Euler2D.load_euler_sim(file_path)
@@ -30,14 +60,15 @@ function FlowData(file_path::String, mach_to_m_s=true)
         cell_ids = nothing
         density_field, velocity_field, pressure_field = convert_to_primitive(u, ncells, nsteps, mach_to_m_s)
     elseif endswith(file_path, ".celltape")
+        # for celltape files, velocity field is currently already m_s. No feature to convert it to mach number.
         sim_data = Euler2D.load_cell_sim(file_path)
         ncells = sim_data.ncells
         nsteps = sim_data.nsteps
         bounds = sim_data.bounds
         tsteps = sim_data.tsteps
         cell_ids = sim_data.cell_ids
         u = nothing
-        density_field, velocity_field, pressure_field = convert_to_primitive(sim_data, nsteps, mach_to_m_s)
+        density_field, velocity_field, pressure_field = convert_to_primitive(sim_data, nsteps)
     else
         error("Unsupported file type. Please provide a .tape  or .celltape file.")
     end

src/pipeline.jl

@@ -2,6 +2,19 @@ using TimerOutputs
 
 abstract type AbstractShockDetectionResult end
 
+"""
+    struct ShockDetectionResult2D <: AbstractShockDetectionResult
+
+A structure to hold the results of 2D shock detection.
+
+# Fields
+- `shock_positions_over_time::Vector{Any}`: A vector of the CartesianIndices of shock points detected in every time frame.
+- `shock_clusters_over_time::Vector{Any}`: A vector of groups of clustered shock points detected in every time frame.
+- `shock_fits_over_time::Vector{Any}`: Fitted shock curves over time. In each time frame is a vector of objects `Fitting`
+
+# Description
+This structure is used to store the results of shock detection in 2D flow data. It contains the detected shock points, clusters of shock points, and fitted shock curves over time.
+"""
 struct ShockDetectionResult2D <: AbstractShockDetectionResult
     shock_positions_over_time::Vector{Any}
     shock_clusters_over_time::Vector{Any}

src/shock_point_detectors/2D/image_processing.jl

@@ -27,7 +27,21 @@ function replace_nan_with_mean!(matrix)
     end
 end
 
+"""
+    struct ImageProcessingShockDetectionAlgo <: Abstract2DShockDetectionAlgo
 
+A structure that represents the image processing shock detection algorithm.
+
+# Fields
+- `threshold::Float64`: The threshold value for detecting shocks.
+- `kernelname::Symbol`: The name of the kernel to be used for image processing (e.g., `:sobel`, `:prewitt`).
+
+# Description
+This struct is used to configure the image processing shock detection algorithm. The algorithm uses a specified kernel to process the image and detect shocks based on the provided threshold value.
+
+# Example
+algo = ImageProcessingShockDetectionAlgo(threshold=0.5, kernelname=:sobel)
+"""
 struct ImageProcessingShockDetectionAlgo <: Abstract2DShockDetectionAlgo
     threshold::Float64
     kernelname::Symbol

src/variable_utils.jl

@@ -77,7 +77,7 @@ function convert_to_primitive(u_values::Array{T, 4}, ncells, nsteps, mach_to_m_s
     return density_field, velocity_field, pressure_field
 end
 
-function convert_to_primitive(sim_data, nsteps, mach_to_m_s=false)
+function convert_to_primitive(sim_data, nsteps)
     density_field = []
     velocity_field = []
     pressure_field = []
@@ -87,13 +87,6 @@ function convert_to_primitive(sim_data, nsteps, mach_to_m_s=false)
         density_t = [x !== nothing ? ustrip(x) : NaN for x in Euler2D.density_field(sim_data, t)]
         pressure_t = Euler2D.pressure_field(sim_data, t, DRY_AIR)
         velocity_t = [x !== nothing ? ustrip(x) : NaN for x in Euler2D.velocity_field(sim_data, t)]
-
-       # TODO: find a way to make this work properly. Since speed of sound needs density or pressure and we have no access to temperature 
-        if mach_to_m_s
-            speed_of_sound_t = [x !== nothing ? ustrip(speed_of_sound(ustrip(x), DRY_AIR)) : NaN for x in pressure_t]
-            #velocity_t = velocity_t .* speed_of_sound_t
-        end
-
         pressure_t = [x !== nothing ? ustrip(x) : NaN for x in pressure_t]
 
         push!(density_field, density_t)