diff --git a/dev/index.html b/dev/index.html index e3e78d2..12191ab 100644 --- a/dev/index.html +++ b/dev/index.html @@ -1,2 +1,2 @@ -Home · PeriodicGraphEmbeddings.jl
Edit on GitHub

PeriodicGraphEmbeddings

A Julia package for manipulating periodic graph embeddings in euclidean spaces, such as those representing atoms in a crystal.

See also:

  • PeriodicGraphs.jl for the all that relates to the periodic graph itself, irrespective of its euclidean embedding.
  • CrystalNets.jl for a dependent package specialized on crystal nets.
+Home · PeriodicGraphEmbeddings.jl
Edit on GitHub

PeriodicGraphEmbeddings

A Julia package for manipulating periodic graph embeddings in euclidean spaces, such as those representing atoms in a crystal.

See also:

  • PeriodicGraphs.jl for the all that relates to the periodic graph itself, irrespective of its euclidean embedding.
  • CrystalNets.jl for a dependent package specialized on crystal nets.
diff --git a/dev/io/index.html b/dev/io/index.html index ce869e5..a249362 100644 --- a/dev/io/index.html +++ b/dev/io/index.html @@ -1,3 +1,3 @@ -I/O · PeriodicGraphEmbeddings.jl
Edit on GitHub

I/O

PeriodicGraphEmbeddings.export_vtf — Function
function export_vtf(file::AbstractString, pge::PeriodicGraphEmbedding3D{T}, types=nothing, repeatedges=6, colorname=false, tostring=string, atomnumof==(a,i)->(a isa Integer ? a : i)) where T

Export a PeriodicGraphEmbedding3D to a .vtf file (readable by VMD).

If specified, types is a list of types for each vertex of pge. Each type is converted to string by the tostring function. The atomnumof function takes two arguments ty and i where ty is a type and i is the number of the vertex, and return an Int representing an atom number.

source
PeriodicGraphEmbeddings.export_cgd — Function
export_cgd(file, pge::PeriodicGraphEmbedding, name=basename(splitext(file)[1]), append=false)
-export_cgd(file, g::PeriodicGraph, name=basename(splitext(file)[1]), append=false)

Export a PeriodicGraph or a PeriodicGraphEmbedding to a .cgd file (readable by Systre).

If append is set, the graph is added at the end of the file.

source
+I/O · PeriodicGraphEmbeddings.jl
Edit on GitHub

I/O

PeriodicGraphEmbeddings.export_vtf — Function
function export_vtf(file::AbstractString, pge::PeriodicGraphEmbedding3D{T}, types=nothing, repeatedges=6, colorname=false, tostring=string, atomnumof==(a,i)->(a isa Integer ? a : i)) where T

Export a PeriodicGraphEmbedding3D to a .vtf file (readable by VMD).

If specified, types is a list of types for each vertex of pge. Each type is converted to string by the tostring function. The atomnumof function takes two arguments ty and i where ty is a type and i is the number of the vertex, and return an Int representing an atom number.

source
PeriodicGraphEmbeddings.export_cgd — Function
export_cgd(file, pge::PeriodicGraphEmbedding, name=basename(splitext(file)[1]), append=false)
+export_cgd(file, g::PeriodicGraph, name=basename(splitext(file)[1]), append=false)

Export a PeriodicGraph or a PeriodicGraphEmbedding to a .cgd file (readable by Systre).

If append is set, the graph is added at the end of the file.

source
diff --git a/dev/search/index.html b/dev/search/index.html index aefa760..5423e81 100644 --- a/dev/search/index.html +++ b/dev/search/index.html @@ -1,2 +1,2 @@ -Search · PeriodicGraphEmbeddings.jl

Loading search...

    +Search · PeriodicGraphEmbeddings.jl

    Loading search...

      diff --git a/dev/symmetries/index.html b/dev/symmetries/index.html index f9b3462..f12c5ae 100644 --- a/dev/symmetries/index.html +++ b/dev/symmetries/index.html @@ -1,2 +1,2 @@ -Symmetries · PeriodicGraphEmbeddings.jl
      Edit on GitHub

      Symmetries

      Symmetry detection is provided by the spglib library, wrapped in helper functions detailed below.

      Manual

      The main function is find_symmetries which returns a SymmetryGroup3D:

      PeriodicGraphEmbeddings.find_symmetries — Function
      find_symmetries(pge::PeriodicGraphEmbedding3D, vtypes=nothing, check_symmetry=check_valid_symmetry; tolerance::Union{Nothing,Cdouble}=nothing)

      Return a SymmetryGroup3D object storing the list of symmetry operations on the graph embedding, found using spglib. Use retrieve_symmetries to simply extract the symmetries already specified in the Cell of the graph embedding.

      If vtypes !== nothing, ensure that two vertices x and y cannot be symmetry-related if vtypes[x] != vtypes[y].

      check_symmetry must be a function that takes the same four arguments pge, t, r and vtypes as check_valid_symmetry and return either (vmap, offsets) or nothing if the input is not a valid symmetry. It can be used to specify additional constraints that cannot be carried by vtypes alone.

      An explicit tolerance can be set. Otherwise, the default is a loose tolerance if the positions are floating points, or a stringent tolerance if they are rationals.

      source

      Space group database API

      PeriodicGraphEmbeddings.SPACE_GROUP_HALL — Constant

      Dictionnary mapping the Hall symbol of a symmetry group to its Hall number.

      In the keys, letters are lowercase, underscores are removed and space is kept to differentiate "p 6 2" from "p 62" and "p 3 2" from "p 32"

      source
      PeriodicGraphEmbeddings.SPACE_GROUP_FULL — Constant

      Dictionnary mapping the full notation representation of a symmetry group to its Hall number, if the full notation is distinct from the H-M symbol.

      In the keys, letters are lowercase and space is removed.

      source

      Internal API

      PeriodicGraphEmbeddings.find_hall_number — Function
      find_hall_number(hallsymbol::AbstractString, hm::AbstractString=hallsymbol, it::Integer=0, warnonnotfound=false)

      Determine the hall number corresponding to the given hallsymbol. The Hermann-Mauguin symbol hm can alternatively be used, or simply the International Table number of the space group it to get the hall number of the standard setting of the group.

      Passing an empty string to hallsymbol or hm or 0 to it disregards the argument.

      The optional argument warnonnotfound specifies whether to print a warning if one of the provided arguments was not reckognized.

      source
      PeriodicGraphEmbeddings.SpglibDataset — Type
      SpglibDataset

      Wrapper around the SpglibDataset type exported by spglib. Its accessible fields are the same as in the C counterpart, except that strings are already converted to String, lists to Vector and matrices to Matrix.

      To access the raw pointers without conversion, prepend an underscore to the field: for example dataset._rotations yields a Ptr{Cint} where dataset.rotations is a 3×3 Matrix{Int}.

      source
      PeriodicGraphEmbeddings.get_spglib_dataset — Function
      get_spglib_dataset(pge::PeriodicGraphEmbedding3D, vtypes=nothing; tolerance::Union{Nothing,Cdouble}=nothing)

      Wrapper around spg_get_dataset.

      If vtypes !== nothing, ensure that two vertices x and y cannot be symmetry-related if vtypes[x] != vtypes[y].

      An explicit tolerance can be set. Otherwise, the default is a loose tolerance if the positions are floating points, or a stringent tolerance if they are rationals.

      source
      PeriodicGraphEmbeddings.check_valid_symmetry — Function
      check_valid_symmetry(pge::PeriodicGraphEmbedding{D,T}, t::SVector{D,T}, r=nothing, vtypes=nothing, issorted=false)

      Check that the periodic graph embedding is identical to that rotated by r (if it is not nothing) then translated by t. If vtypes is not nothing, any vertex x must additionally be mapped to a vertex y such that vtypes[x] == vtypes[y]. If issorted is set and T <: Rational, assume that issorted(pge.pos) to use a faster dichotomy approach.

      If so, return the the vmap between the initial vertices and their symmetric images, as well as the offsets of each symmetric image compared to the origin. Otherwise, return nothing.

      source
      +Symmetries · PeriodicGraphEmbeddings.jl
      Edit on GitHub

      Symmetries

      Symmetry detection is provided by the spglib library, wrapped in helper functions detailed below.

      Manual

      The main function is find_symmetries which returns a SymmetryGroup3D:

      PeriodicGraphEmbeddings.find_symmetries — Function
      find_symmetries(pge::PeriodicGraphEmbedding3D, vtypes=nothing, check_symmetry=check_valid_symmetry; tolerance::Union{Nothing,Cdouble}=nothing)

      Return a SymmetryGroup3D object storing the list of symmetry operations on the graph embedding, found using spglib. Use retrieve_symmetries to simply extract the symmetries already specified in the Cell of the graph embedding.

      If vtypes !== nothing, ensure that two vertices x and y cannot be symmetry-related if vtypes[x] != vtypes[y].

      check_symmetry must be a function that takes the same four arguments pge, t, r and vtypes as check_valid_symmetry and return either (vmap, offsets) or nothing if the input is not a valid symmetry. It can be used to specify additional constraints that cannot be carried by vtypes alone.

      An explicit tolerance can be set. Otherwise, the default is a loose tolerance if the positions are floating points, or a stringent tolerance if they are rationals.

      source

      Space group database API

      PeriodicGraphEmbeddings.SPACE_GROUP_HALL — Constant

      Dictionnary mapping the Hall symbol of a symmetry group to its Hall number.

      In the keys, letters are lowercase, underscores are removed and space is kept to differentiate "p 6 2" from "p 62" and "p 3 2" from "p 32"

      source
      PeriodicGraphEmbeddings.SPACE_GROUP_FULL — Constant

      Dictionnary mapping the full notation representation of a symmetry group to its Hall number, if the full notation is distinct from the H-M symbol.

      In the keys, letters are lowercase and space is removed.

      source

      Internal API

      PeriodicGraphEmbeddings.find_hall_number — Function
      find_hall_number(hallsymbol::AbstractString, hm::AbstractString=hallsymbol, it::Integer=0, warnonnotfound=false)

      Determine the hall number corresponding to the given hallsymbol. The Hermann-Mauguin symbol hm can alternatively be used, or simply the International Table number of the space group it to get the hall number of the standard setting of the group.

      Passing an empty string to hallsymbol or hm or 0 to it disregards the argument.

      The optional argument warnonnotfound specifies whether to print a warning if one of the provided arguments was not reckognized.

      source
      PeriodicGraphEmbeddings.SpglibDataset — Type
      SpglibDataset

      Wrapper around the SpglibDataset type exported by spglib. Its accessible fields are the same as in the C counterpart, except that strings are already converted to String, lists to Vector and matrices to Matrix.

      To access the raw pointers without conversion, prepend an underscore to the field: for example dataset._rotations yields a Ptr{Cint} where dataset.rotations is a 3×3 Matrix{Int}.

      source
      PeriodicGraphEmbeddings.get_spglib_dataset — Function
      get_spglib_dataset(pge::PeriodicGraphEmbedding3D, vtypes=nothing; tolerance::Union{Nothing,Cdouble}=nothing)

      Wrapper around spg_get_dataset.

      If vtypes !== nothing, ensure that two vertices x and y cannot be symmetry-related if vtypes[x] != vtypes[y].

      An explicit tolerance can be set. Otherwise, the default is a loose tolerance if the positions are floating points, or a stringent tolerance if they are rationals.

      source
      PeriodicGraphEmbeddings.check_valid_symmetry — Function
      check_valid_symmetry(pge::PeriodicGraphEmbedding{D,T}, t::SVector{D,T}, r=nothing, vtypes=nothing, issorted=false)

      Check that the periodic graph embedding is identical to that rotated by r (if it is not nothing) then translated by t. If vtypes is not nothing, any vertex x must additionally be mapped to a vertex y such that vtypes[x] == vtypes[y]. If issorted is set and T <: Rational, assume that issorted(pge.pos) to use a faster dichotomy approach.

      If so, return the the vmap between the initial vertices and their symmetric images, as well as the offsets of each symmetric image compared to the origin. Otherwise, return nothing.

      source
      diff --git a/dev/types/index.html b/dev/types/index.html index 4a9f83c..54eb457 100644 --- a/dev/types/index.html +++ b/dev/types/index.html @@ -1,12 +1,12 @@ -Types · PeriodicGraphEmbeddings.jl
      Edit on GitHub

      Types

      Manual

      PeriodicGraphEmbeddings provide the new type PeriodicGraphEmbedding which wraps:

      1. A PeriodicGraph
      2. The list of positions of the vertices in a unit cell of the graph
      3. Optionally, a Cell if the dimension of the graph is 3 or below, which contains the geometry of the unit cell.

      A PeriodicGraphEmbedding can be built through different methods, depending on whether the list of positions should be permuted to be sorted, or offset to have all positions between 0 and 1 for instance:

      PeriodicGraphEmbeddings.PeriodicGraphEmbedding — Type
      PeriodicGraphEmbedding{D,T}

      Embedding in euclidean space of a PeriodicGraph of dimension D. Each vertex is assigned a D-uplet of coordinates of type T.

      PeriodicGraphEmbedding3D is provided as an alias for PeriodicGraphEmbedding{3}. Symmetry detection provided by PeriodicGraphEmbeddings.jl can only be performed on PeriodicGraphEmbedding3D.

      source
      PeriodicGraphEmbeddings.PeriodicGraphEmbedding — Method
      PeriodicGraphEmbedding{D,T}(graph::PeriodicGraph{D}, placement::AbstractMatrix{T}, cell::Cell=Cell()) where {D,T}
+Types · PeriodicGraphEmbeddings.jl
      Edit on GitHub
      Types
      Manual
      PeriodicGraphEmbeddings provide the new type PeriodicGraphEmbedding which wraps:
      1. A PeriodicGraph
      2. The list of positions of the vertices in a unit cell of the graph
      3. Optionally, a Cell if the dimension of the graph is 3 or below, which contains the geometry of the unit cell.
      A PeriodicGraphEmbedding can be built through different methods, depending on whether the list of positions should be permuted to be sorted, or offset to have all positions between 0 and 1 for instance:
      PeriodicGraphEmbeddings.PeriodicGraphEmbedding — Type
      PeriodicGraphEmbedding{D,T}
      Embedding in euclidean space of a PeriodicGraph of dimension D. Each vertex is assigned a D-uplet of coordinates of type T.
      PeriodicGraphEmbedding3D is provided as an alias for PeriodicGraphEmbedding{3}. Symmetry detection provided by PeriodicGraphEmbeddings.jl can only be performed on PeriodicGraphEmbedding3D.
      source
      PeriodicGraphEmbeddings.PeriodicGraphEmbedding — Method
      PeriodicGraphEmbedding{D,T}(graph::PeriodicGraph{D}, placement::AbstractMatrix{T}, cell::Cell=Cell()) where {D,T}
 PeriodicGraphEmbedding{D}(graph::PeriodicGraph{D}, placement::AbstractMatrix{T}, cell::Cell=Cell()) where D
-PeriodicGraphEmbedding(graph::PeriodicGraph{D}, placement::AbstractMatrix{T}, cell::Cell=Cell())
      Build a PeriodicGraphEmbedding{D,T} from the corresponding graph and placement of the vertices, such that each vertex has its fractional coordinate represented in a column of the matrix.
      Coordinates out of [0, 1) are translated back to the unit cell with the corresponding offset added to the graph.
      The cell optional argument will not be used if D > 3.
      Warning
      This function modifies the input graph if any element of placement is out of [0, 1).
      Note
      To obtain a PeriodicGraphEmbedding with sorted positions, use SortedPeriodicGraphEmbedding instead
      source
      PeriodicGraphEmbeddings.SortedPeriodicGraphEmbedding — Method
      SortedPeriodicGraphEmbedding{T}(graph::PeriodicGraph{D}, placement::AbstractMatrix, cell::Cell=Cell()) where {D,T}
      Build a PeriodicGraphEmbedding{D,T} from the corresponding graph and placement of the vertices, so that the result has its vertices sorted by position.
      Return the PeriodicGraphEmbedding as well as the permutation of the columns of placement that yielded the resulting order on the vertices.
      The cell optional argument will not be used if D > 3.
      Warning
      This function modifies the input graph if any element of placement is out of [0, 1).
      See also PeriodicGraphEmbedding{D,T}(graph, placement::AbstractMatrix{T}, cell) where {D,T} and SortedPeriodicGraphEmbedding(graph, placement::AbstractMatrix, cell).
      source
      SortedPeriodicGraphEmbedding(graph::PeriodicGraph{D}, placement::AbstractMatrix, cell::Cell=Cell()) where D
      Build a PeriodicGraphEmbedding{D,T} from the corresponding graph and placement of the vertices, so that the result has its vertices sorted by position. T is determined as the smallest type between Rational{Int32}, Rational{Int64}, Rational{Int128} and Rational{BigInt} that can fit all the elements of placement with some additional margin.
      Return the PeriodicGraphEmbedding as well as the permutation of the columns of placement that yielded the resulting order on the vertices.
      The cell optional argument will not be used if D > 3.
      Warning
      This function modifies the input graph if any element of placement is out of [0, 1).
      Tip
      This function is inherently type-unstable since T cannot be statically determined. This can be useful because having a too large T may slow down later computations.
      To provide the parameter explicitly, pass it to the SortedPeriodicGraphEmbedding constructor by calling SortedPeriodicGraphEmbedding{T}(graph, placement, cell).
      See also PeriodicGraphEmbedding{D,T}(graph, placement::AbstractMatrix{T}, cell) where {D,T}.
      source
      PeriodicGraphEmbeddings.PeriodicGraphEmbedding — Method
      PeriodicGraphEmbedding{D,T}(pge::PeriodicGraphEmbedding{N,S}) where {D,T,N,S}
-PeriodicGraphEmbedding{D}(pge::PeriodicGraphEmbedding{N,S}) where {D,N,S}
      Return a PeriodicGraphEmbedding{D,T} with the same structural information as the input pge but embedded in D dimensions instead of N.
      If T is not provided it defaults to S.
      The same caveats that apply to PeriodicGraph{D}(graph::PeriodicGraph{N}) are valid here: namely, the dimensionality of the graph should be at least D and the behaviour is undefined if D < N and there are multiple non-identical connected components.
      Moreover, if D < N, the N-D last coordinates of all vertices must be zero or this function will error.
      source
      Cell API
      PeriodicGraphEmbeddings.cell_parameters — Function
      cell_parameters(cell::Cell)
      Return ((lengths, angles), mat) where mat is the matrix of the cell in upper triangular format, lengths is the triplet (a, b, c) of lengths of the three axes, and angles is the triplet (α, β, γ) of angles between them.
      source
      PeriodicGraphEmbeddings.EquivalentPosition — Type
      EquivalentPosition{T}
      Representation of a symmetry operation in 3D, defined by a matrix multiplication and addition.
      Example
      julia> eq = parse(EquivalentPosition, "1-x, z, y+1/2")
+PeriodicGraphEmbedding(graph::PeriodicGraph{D}, placement::AbstractMatrix{T}, cell::Cell=Cell())
      Build a PeriodicGraphEmbedding{D,T} from the corresponding graph and placement of the vertices, such that each vertex has its fractional coordinate represented in a column of the matrix.
      Coordinates out of [0, 1) are translated back to the unit cell with the corresponding offset added to the graph.
      The cell optional argument will not be used if D > 3.
      Warning
      This function modifies the input graph if any element of placement is out of [0, 1).
      Note
      To obtain a PeriodicGraphEmbedding with sorted positions, use SortedPeriodicGraphEmbedding instead
      source
      PeriodicGraphEmbeddings.SortedPeriodicGraphEmbedding — Method
      SortedPeriodicGraphEmbedding{T}(graph::PeriodicGraph{D}, placement::AbstractMatrix, cell::Cell=Cell()) where {D,T}
      Build a PeriodicGraphEmbedding{D,T} from the corresponding graph and placement of the vertices, so that the result has its vertices sorted by position.
      Return the PeriodicGraphEmbedding as well as the permutation of the columns of placement that yielded the resulting order on the vertices.
      The cell optional argument will not be used if D > 3.
      Warning
      This function modifies the input graph if any element of placement is out of [0, 1).
      See also PeriodicGraphEmbedding{D,T}(graph, placement::AbstractMatrix{T}, cell) where {D,T} and SortedPeriodicGraphEmbedding(graph, placement::AbstractMatrix, cell).
      source
      SortedPeriodicGraphEmbedding(graph::PeriodicGraph{D}, placement::AbstractMatrix, cell::Cell=Cell()) where D
      Build a PeriodicGraphEmbedding{D,T} from the corresponding graph and placement of the vertices, so that the result has its vertices sorted by position. T is determined as the smallest type between Rational{Int32}, Rational{Int64}, Rational{Int128} and Rational{BigInt} that can fit all the elements of placement with some additional margin.
      Return the PeriodicGraphEmbedding as well as the permutation of the columns of placement that yielded the resulting order on the vertices.
      The cell optional argument will not be used if D > 3.
      Warning
      This function modifies the input graph if any element of placement is out of [0, 1).
      Tip
      This function is inherently type-unstable since T cannot be statically determined. This can be useful because having a too large T may slow down later computations.
      To provide the parameter explicitly, pass it to the SortedPeriodicGraphEmbedding constructor by calling SortedPeriodicGraphEmbedding{T}(graph, placement, cell).
      See also PeriodicGraphEmbedding{D,T}(graph, placement::AbstractMatrix{T}, cell) where {D,T}.
      source
      PeriodicGraphEmbeddings.PeriodicGraphEmbedding — Method
      PeriodicGraphEmbedding{D,T}(pge::PeriodicGraphEmbedding{N,S}) where {D,T,N,S}
+PeriodicGraphEmbedding{D}(pge::PeriodicGraphEmbedding{N,S}) where {D,N,S}
      Return a PeriodicGraphEmbedding{D,T} with the same structural information as the input pge but embedded in D dimensions instead of N.
      If T is not provided it defaults to S.
      The same caveats that apply to PeriodicGraph{D}(graph::PeriodicGraph{N}) are valid here: namely, the dimensionality of the graph should be at least D and the behaviour is undefined if D < N and there are multiple non-identical connected components.
      Moreover, if D < N, the N-D last coordinates of all vertices must be zero or this function will error.
      source
      Cell API
      PeriodicGraphEmbeddings.cell_parameters — Function
      cell_parameters(cell::Cell)
      Return ((lengths, angles), mat) where mat is the matrix of the cell in upper triangular format, lengths is the triplet (a, b, c) of lengths of the three axes, and angles is the triplet (α, β, γ) of angles between them.
      source
      PeriodicGraphEmbeddings.EquivalentPosition — Type
      EquivalentPosition{T}
      Representation of a symmetry operation in 3D, defined by a matrix multiplication and addition.
      Example
      julia> eq = parse(EquivalentPosition, "1-x, z, y+1/2")
 -x+1,z,y+1/2
 
 julia> eq([1//3, 0, 1//4])
 3-element StaticArrays.SVector{3, Rational{Int64}} with indices SOneTo(3):
  2//3
  1//4
- 1//2
      The type parameter T is the numeric type used to store the symmetry operations. It should be typically either Rational{Int} or Float64.
      source
      Missing docstring.
      Missing docstring for Base.parse(::Type{EquivalentPosition}, s::AbstractString). Check Documenter's build log for details.
      PeriodicGraphEmbeddings.find_refid — Function
      find_refid(eqs)
      Find the reference identifiers for the three dimensions for the CIF group called symmetry_equiv_pos_as_xyz or space_group_symop_operation_xyz. Usually this is simply ("x", "y", "z").
      source
      
+ 1//2

      The type parameter T is the numeric type used to store the symmetry operations. It should be typically either Rational{Int} or Float64.

      source
      Missing docstring.

      Missing docstring for Base.parse(::Type{EquivalentPosition}, s::AbstractString). Check Documenter's build log for details.

      PeriodicGraphEmbeddings.find_refid — Function
      find_refid(eqs)

      Find the reference identifiers for the three dimensions for the CIF group called symmetry_equiv_pos_as_xyz or space_group_symop_operation_xyz. Usually this is simply ("x", "y", "z").

      source
      diff --git a/dev/utilities/index.html b/dev/utilities/index.html index d513cc1..506b51d 100644 --- a/dev/utilities/index.html +++ b/dev/utilities/index.html @@ -21,4 +21,4 @@ true julia> pd2(mat*vec1, mat*vec2; fromcartesian=true) ≈ d2 -truesource

      Other

      PeriodicGraphEmbeddings.double_widen — Function
      double_widen(::Type)

      Internal function used to selectively widen small integer and rational types.

      This is useful to avoid overflow without sacrificing too much efficiency by always having to resolve to very large types.

      source
      +truesource

      Other

      PeriodicGraphEmbeddings.double_widen — Function
      double_widen(::Type)

      Internal function used to selectively widen small integer and rational types.

      This is useful to avoid overflow without sacrificing too much efficiency by always having to resolve to very large types.

      source