Merge pull request #180 from navidcy/ncc/docstring

.github/DocPreviewCleanup.yml

@@ -0,0 +1,26 @@
+name: Doc Preview Cleanup
+
+on:
+  pull_request:
+    types: [closed]
+
+jobs:
+  doc-preview-cleanup:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout gh-pages branch
+        uses: actions/checkout@v4
+        with:
+          ref: gh-pages
+      - name: Delete preview and history + push changes
+        run: |
+            if [ -d "previews/PR$PRNUM" ]; then
+              git config user.name "Documenter.jl"
+              git config user.email "[email protected]"
+              git rm -rf "previews/PR$PRNUM"
+              git commit -m "delete preview"
+              git branch gh-pages-new $(echo "delete history" | git commit-tree HEAD^{tree})
+              git push --force origin gh-pages-new:gh-pages
+            fi
+        env:
+            PRNUM: ${{ github.event.number }}

docs/make.jl

@@ -34,5 +34,6 @@ makedocs(;
 )
 
 deploydocs(;
-    repo="github.com/numericalEFT/FeynmanDiagram.jl"
+    repo="github.com/numericalEFT/FeynmanDiagram.jl",
+    push_preview=true
 )

src/computational_graph/feynmangraph.jl

@@ -212,71 +212,71 @@ set_subgraph_factors!(g::FeynmanGraph{F,W}, subgraph_factors::AbstractVector, in
 """
 function is_external_operators(g::FeynmanGraph, i) 
 
-    Check if `i` in the external indices of FeynmanGraph `g`.
+Check if `i` in the external indices of FeynmanGraph `g`.
 """
 is_external(g::FeynmanGraph, i) = i in g.properties.external_indices
 
 """
     function is_internal(g::FeynmanGraph, i) 
 
-    Check if `i` in the internal indices of FeynmanGraph `g`.
+Check if `i` in the internal indices of FeynmanGraph `g`.
 """
 is_internal(g::FeynmanGraph, i) = (i in g.properties.external_indices) == false
 
 """
     function diagram_type(g::FeynmanGraph)
 
-    Returns the diagram type (::DiagramType) of FeynmanGraph `g`.
+Returns the diagram type (::DiagramType) of FeynmanGraph `g`.
 """
 diagram_type(g::FeynmanGraph) = g.properties.diagtype
 
 """
     function vertices(g::FeynmanGraph)
 
-    Returns all vertices (::Vector{OperatorProduct}) of FeynmanGraph `g`.
+Returns all vertices (::Vector{OperatorProduct}) of FeynmanGraph `g`.
 """
 vertices(g::FeynmanGraph) = g.properties.vertices
 
 """
     function vertex(g::FeynmanGraph, i=1)
 
-    Returns the `i`th vertex (::OperatorProduct) of FeynmanGraph `g`.
-    Defaults to the first vertex if an index `i` is not supplied.
+Returns the `i`th vertex (::OperatorProduct) of FeynmanGraph `g`.
+Defaults to the first vertex if an index `i` is not supplied.
 """
 vertex(g::FeynmanGraph, i=1) = g.properties.vertices[i]
 
 """
     function topology(g::FeynmanGraph)
 
-    Returns the topology (::Vector{Vector{Int}}) of FeynmanGraph `g`.
+Returns the topology (::Vector{Vector{Int}}) of FeynmanGraph `g`.
 """
 topology(g::FeynmanGraph) = g.properties.topology
 
 """
     function external_legs(g::FeynmanGraph)
 
-    Returns a list of Boolean indices external_legs (::Vector{Bool}) indicating which external vertices of FeynmanGraph `g` have real legs (true: real leg, false: fake leg).
+Returns a list of Boolean indices external_legs (::Vector{Bool}) indicating which external vertices of FeynmanGraph `g` have real legs (true: real leg, false: fake leg).
 """
 external_legs(g::FeynmanGraph) = g.properties.external_legs
 
 """
     function external_indices(g::FeynmanGraph)
 
-    Returns a list of indices (::Vector{Int}}) to the external vertices of the FeynmanGraph `g`.
+Returns a list of indices (::Vector{Int}}) to the external vertices of the FeynmanGraph `g`.
 """
 external_indices(g::FeynmanGraph) = g.properties.external_indices
 
 """
     function external_operators(g::FeynmanGraph)
 
-    Returns all physical external operators (::OperatorProduct}) of FeynmanGraph `g`.
+Returns all physical external operators (::OperatorProduct}) of FeynmanGraph `g`.
 """
 external_operators(g::FeynmanGraph) = OperatorProduct(OperatorProduct(g.properties.vertices)[g.properties.external_indices])
 
 """
     function external_labels(g::FeynmanGraph)
 
-    Returns the labels of all physical external vertices of FeynmanGraph `g`.
+Returns the labels of all physical external vertices of FeynmanGraph `g`.
 """
 external_labels(g::FeynmanGraph) = [o.label for o in external_operators(g)]
 
@@ -295,7 +295,7 @@ end
 """
     function Base.:*(g1::Graph{F,W}, c2) where {F,W}
 
-    Returns a graph representing the scalar multiplication `g1*c2`.
+Returns a graph representing the scalar multiplication `g1*c2`.
 
 # Arguments:
 - `g1`  Feynman graph
@@ -314,7 +314,7 @@ end
 """
     function Base.:*(c1, g2::Graph{F,W}) where {F,W}
 
-    Returns a graph representing the scalar multiplication `c1*g2`.
+Returns a graph representing the scalar multiplication `c1*g2`.
 
 # Arguments:
 - `c1`  scalar multiple
@@ -333,8 +333,8 @@ end
 """
     function linear_combination(g1::FeynmanGraph{F,W}, g2::FeynmanGraph{F,W}, c1, c2) where {F,W}
 
-    Returns a graph representing the linear combination `c1*g1 + c2*g2`. If `g1 == g2`, it will return a graph representing `(c1+c2)*g1`
-    Feynman Graphs `g1` and `g2` must have the same diagram type, orders, and external vertices.
+Returns a graph representing the linear combination `c1*g1 + c2*g2`. If `g1 == g2`, it will return a graph representing `(c1+c2)*g1`
+Feynman Graphs `g1` and `g2` must have the same diagram type, orders, and external vertices.
 
 # Arguments:
 - `g1`  first Feynman graph
@@ -376,10 +376,10 @@ end
 """
     function linear_combination(graphs::Vector{FeynmanGraph{F,W}}, constants::AbstractVector=ones(F, length(graphs))) where {F,W}
 
-    Given a vector 𝐠 of graphs each with the same type and external/internal vertices and 
-    an equally-sized vector 𝐜 of constants, returns a new graph representing the linear combination (𝐜 ⋅ 𝐠). 
-    The function identifies unique graphs from the input `graphs` and sums their associated `constants`.
-    All input Graphs must have the same diagram type, orders, and external vertices.
+Given a vector 𝐠 of graphs each with the same type and external/internal vertices and 
+an equally-sized vector 𝐜 of constants, returns a new graph representing the linear combination (𝐜 ⋅ 𝐠). 
+The function identifies unique graphs from the input `graphs` and sums their associated `constants`.
+All input Graphs must have the same diagram type, orders, and external vertices.
 
 # Arguments:
 - `graphs`  vector of input FeymanGraphs
@@ -429,8 +429,8 @@ end
 """
     function Base.:+(g1::Graph{F,W}, g2::Graph{F,W}) where {F,W}
 
-    Returns a graph `g1 + g2` representing the addition of two Feynman diagrams `g2` with `g1`.
-    Diagrams `g1` and `g2` must have the same diagram type, orders, and external vertices.
+Returns a graph `g1 + g2` representing the addition of two Feynman diagrams `g2` with `g1`.
+Diagrams `g1` and `g2` must have the same diagram type, orders, and external vertices.
 
 # Arguments:
 - `g1`  first Feynman graph
@@ -443,8 +443,8 @@ end
 """
     function Base.:-(g1::Graph{F,W}, g2::Graph{F,W}) where {F,W}
 
-    Returns a graph `g1 - g2` representing the subtraction of `g2` from `g1`.
-    Diagrams `g1` and `g2` must have the same diagram type, orders, and external vertices.
+Returns a graph `g1 - g2` representing the subtraction of `g2` from `g1`.
+Diagrams `g1` and `g2` must have the same diagram type, orders, and external vertices.
 
 # Arguments:
 - `g1`  first Feynman graph
@@ -462,9 +462,9 @@ end
     function feynman_diagram(subgraphs::Vector{FeynmanGraph{F,W}}, topology::Vector{Vector{Int}}, perm_noleg::Union{Vector{Int},Nothing}=nothing;
         factor=one(_dtype.factor), weight=zero(_dtype.weight), name="", diagtype::DiagramType=GenericDiag()) where {F,W}
     
-    Create a FeynmanGraph representing feynman diagram from all subgraphs and topology (connections between vertices),
-    where each ExternalVertex is given in `vertices`, 
-    while internal vertices are constructed with external legs of graphs in `vertices`, or simply OperatorProduct in `vertices`.
+Create a FeynmanGraph representing feynman diagram from all subgraphs and topology (connections between vertices),
+where each ExternalVertex is given in `vertices`, 
+while internal vertices are constructed with external legs of graphs in `vertices`, or simply OperatorProduct in `vertices`.
     
 # Arguments:
 - `subgraphs::Vector{FeynmanGraph{F,W}}` all subgraphs of the diagram. All external operators of subgraphs constitute all operators of the new diagram.
@@ -574,7 +574,7 @@ _extract_vertex(::Type{<:FeynmanGraph}, g) = OperatorProduct(external_operators(
     function propagator(ops::Union{OperatorProduct,Vector{QuantumOperator}};
         name="", factor=one(_dtype.factor), weight=zero(_dtype.weight), operator=Sum())
 
-    Create a Propagator-type FeynmanGraph from given OperatorProduct or Vector{QuantumOperator} `ops`, including two quantum operators.
+Create a Propagator-type FeynmanGraph from given OperatorProduct or Vector{QuantumOperator} `ops`, including two quantum operators.
 """
 function propagator(ops::Union{OperatorProduct,Vector{QuantumOperator}}; orders::Union{Nothing,Vector{Int}}=nothing,
     name="", factor=one(_dtype.factor), weight=zero(_dtype.weight), operator=Sum())
@@ -593,8 +593,9 @@ end
 """
     function interaction(ops::OperatorProduct; name="", reorder::Union{Function,Nothing}=nothing,
         factor=one(_dtype.factor), weight=zero(_dtype.weight), operator=Sum())
-    Create a Interaction-type FeynmanGraph from given OperatorProduct `ops`, including several quantum operators for a vertex.
-    One can call a reorder function for the operators ordering.  
+
+Create a Interaction-type FeynmanGraph from given OperatorProduct `ops`, including several quantum operators for a vertex.
+One can call a reorder function for the operators ordering.  
 """
 function interaction(ops::OperatorProduct; name="", reorder::Union{Function,Nothing}=nothing,
     factor=one(_dtype.factor), weight=zero(_dtype.weight), operator=Sum())
@@ -612,7 +613,8 @@ end
 """
     function external_vertex(ops::OperatorProduct;
         name="", factor=one(_dtype.factor), weight=zero(_dtype.weight), operator=Sum())
-    Create a ExternalVertex-type FeynmanGraph from given OperatorProduct `ops`, including several quantum operators for an purely external vertex.
+
+Create a ExternalVertex-type FeynmanGraph from given OperatorProduct `ops`, including several quantum operators for an purely external vertex.
 """
 function external_vertex(ops::OperatorProduct;
     name="", factor=one(_dtype.factor), weight=zero(_dtype.weight), operator=Sum())

src/computational_graph/graph.jl

@@ -1,7 +1,7 @@
 """
     mutable struct Graph{F<:Number,W}
     
-    A representation of a computational graph, e.g., an expression tree, with type stable node data.
+A representation of a computational graph, e.g., an expression tree, with type stable node data.
 
 # Members:
 - `id::Int`  the unique hash id to identify the diagram
@@ -37,11 +37,12 @@ mutable struct Graph{F<:Number,W} <: AbstractGraph # Graph
     weight::W
 
     properties::Any
+
     """
         function Graph(subgraphs::AbstractVector; name="", operator::AbstractOperator=Sum(),
             ftype=_dtype.factor, wtype=_dtype.weight, factor=one(ftype), weight=zero(wtype))
         
-        Create a Graph struct from a set of subgraphs with the specified node data and operation.
+    Create a Graph struct from a set of subgraphs with the specified node data and operation.
 
     # Arguments:
     - `subgraphs`  vector of sub-diagrams 
@@ -107,7 +108,7 @@ set_subgraph_factors!(g::Graph{F,W}, subgraph_factors::AbstractVector, indices::
 """
     function constant_graph(factor=one(_dtype.factor))
 
-    Returns a graph that represents a constant equal to f, where f is the factor with default value 1.
+Returns a graph that represents a constant equal to f, where f is the factor with default value 1.
 
 # Arguments:
 - `f`:  constant factor
@@ -124,7 +125,7 @@ end
 """
     function Base.:*(g1::Graph{F,W}, c2) where {F,W}
 
-    Returns a graph representing the scalar multiplication `g1*c2`.
+Returns a graph representing the scalar multiplication `g1*c2`.
 
 # Arguments:
 - `g1`  computational graph
@@ -143,7 +144,7 @@ end
 """
     function Base.:*(c1, g2::Graph{F,W}) where {F,W}
 
-    Returns a graph representing the scalar multiplication `c1*g2`.
+Returns a graph representing the scalar multiplication `c1*g2`.
 
 # Arguments:
 - `c1`  scalar multiple
@@ -162,9 +163,9 @@ end
 """
     function linear_combination(g1::Graph{F,W}, g2::Graph{F,W}, c1, c2) where {F,W}
 
-    Returns a graph representing the linear combination `c1*g1 + c2*g2`.
-    If `g1 == g2`, it will return a graph representing `(c1+c2)*g1`.
-    Graphs `g1` and `g2` must have the same orders.
+Returns a graph representing the linear combination `c1*g1 + c2*g2`.
+If `g1 == g2`, it will return a graph representing `(c1+c2)*g1`.
+Graphs `g1` and `g2` must have the same orders.
 
 # Arguments:
 - `g1`  first computational graph
@@ -206,10 +207,10 @@ end
 """
     function linear_combination(graphs::Vector{Graph{F,W}}, constants::AbstractVector=ones(F, length(graphs))) where {F,W}
 
-    Given a vector 𝐠 of graphs and an equally-sized vector 𝐜 of constants, returns a new
-    graph representing the linear combination (𝐜 ⋅ 𝐠). 
-    The function identifies unique graphs from the input `graphs` and sums their associated `constants`.
-    All input graphs must have the same orders.
+Given a vector 𝐠 of graphs and an equally-sized vector 𝐜 of constants, returns a new
+graph representing the linear combination (𝐜 ⋅ 𝐠). 
+The function identifies unique graphs from the input `graphs` and sums their associated `constants`.
+All input graphs must have the same orders.
 
 # Arguments:
 - `graphs`  vector of computational graphs
@@ -261,8 +262,8 @@ end
 """
     function Base.:+(g1::Graph{F,W}, g2::Graph{F,W}) where {F,W}
 
-    Returns a graph `g1 + g2` representing the addition of `g2` with `g1`.
-    Graphs `g1` and `g2` must have the same orders.
+Returns a graph `g1 + g2` representing the addition of `g2` with `g1`.
+Graphs `g1` and `g2` must have the same orders.
 
 # Arguments:
 - `g1`  first computational graph
@@ -275,8 +276,8 @@ end
 """
     function Base.:-(g1::Graph{F,W}, g2::Graph{F,W}) where {F,W}
 
-    Returns a graph `g1 - g2` representing the subtraction of `g2` from `g1`.
-    Graphs `g1` and `g2` must have the same orders.
+Returns a graph `g1 - g2` representing the subtraction of `g2` from `g1`.
+Graphs `g1` and `g2` must have the same orders.
 
 # Arguments:
 - `g1`  first computational graph
@@ -289,8 +290,8 @@ end
 """
     function multi_product(g1::Graph{F,W}, g2::Graph{F,W}, c1=F(1), c2=F(1)) where {F,W,C}
 
-    Returns a graph representing the multi product `c1*g1 * c2*g2`.
-    If `g1 == g2`, it will return a graph representing `c1*c2 * (g1)^2` with `Power(2)` operator.
+Returns a graph representing the multi product `c1*g1 * c2*g2`.
+If `g1 == g2`, it will return a graph representing `c1*c2 * (g1)^2` with `Power(2)` operator.
 
 # Arguments:
 - `g1`:  first computational graph
@@ -330,9 +331,9 @@ end
 """
     multi_product(graphs::Vector{Graph{F,W}}, constants::AbstractVector=ones(F, length(graphs))) where {F,W,C}
 
-    Construct a product graph from multiple input graphs, where each graph can be weighted by a constant. 
-    For graphs that are repeated more than once, it adds a power operator to the subgraph to represent the repetition.
-    Moreover, it optimizes any trivial unary operators in the resulting product graph.
+Construct a product graph from multiple input graphs, where each graph can be weighted by a constant. 
+For graphs that are repeated more than once, it adds a power operator to the subgraph to represent the repetition.
+Moreover, it optimizes any trivial unary operators in the resulting product graph.
 
 # Arguments:
 - `graphs::Vector{Graph{F,W}}`: A vector of input graphs to be multiplied.
@@ -400,7 +401,7 @@ end
 """
     function Base.:*(g1::Graph{F,W}, g2::Graph{F,W}) where {F,W}
 
-    Returns a graph `g1 * g2` representing the graph product between `g1` and `g2`.
+Returns a graph `g1 * g2` representing the graph product between `g1` and `g2`.
 
 # Arguments:
 - `g1`  first computational graph

src/frontend/parquet/operation.jl

@@ -74,9 +74,9 @@ end
         getid::Function=g -> GenericId(g[1, :diagram].properties.para, Tuple(g[1, fields]))
     )
 
-    Aggregates and merges rows in a DataFrame based on specified fields and an aggregation operator.
-    It is designed to work with data frames containing diagram representations or similar structured data, 
-    allowing for flexible aggregation based on custom identifiers and properties.
+Aggregates and merges rows in a DataFrame based on specified fields and an aggregation operator.
+It is designed to work with data frames containing diagram representations or similar structured data, 
+allowing for flexible aggregation based on custom identifiers and properties.
 
 # Parameters
 - `df`: A DataFrame to be processed. It must contain a column named :diagram which holds `Graph`.
@@ -159,7 +159,7 @@ end
 """
     update_extKT!(diags::Vector{Graph}, para::DiagPara, legK::Vector{Vector{Float64}})
 
-    Update the external momenta (`extK`) and external times (`extT`) of all the nodes in a vector of graphs in-place.
+Update the external momenta (`extK`) and external times (`extT`) of all the nodes in a vector of graphs in-place.
 
 # Arguments
 - `diags::Vector{Graph}`: A vector of `Graph` objects.
@@ -239,8 +239,8 @@ end
 """
     update_extKT(diags::Vector{Graph}, para::DiagPara, legK::Vector{Vector{Float64}}) -> Vector{Graph}
 
-    Returns a new vector of graphs with updated external momenta (`extK`) and external times (`extT`), 
-    based on the provided graphs, parameters, and external legs' momenta.
+Returns a new vector of graphs with updated external momenta (`extK`) and external times (`extT`), 
+based on the provided graphs, parameters, and external legs' momenta.
 
 # Arguments
 - `diags::Vector{Graph}`: A vector of `Graph` objects.