A Julia package for manipulating periodic graph embeddings in euclidean spaces, such as those representing atoms in a crystal.
See also:
Settings
This document was generated with Documenter.jl version 0.27.25 on Tuesday 16 April 2024. Using Julia version 1.6.7.
PeriodicGraphEmbeddings.export_vtf — Functionfunction export_vtf(file::AbstractString, pge::PeriodicGraphEmbedding3D{T}, types=nothing, repeatedges=6, colorname=false, tostring=string, atomnumof==(a,i)->(a isa Integer ? a : i)) where TExport 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.
PeriodicGraphEmbeddings.export_cgd — Functionexport_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.
Settings
This document was generated with Documenter.jl version 0.27.25 on Tuesday 16 April 2024. Using Julia version 1.6.7.
Settings
This document was generated with Documenter.jl version 0.27.25 on Tuesday 16 April 2024. Using Julia version 1.6.7.
Symmetry detection is provided by the spglib library, wrapped in helper functions detailed below.
The main function is find_symmetries which returns a SymmetryGroup3D:
PeriodicGraphEmbeddings.find_symmetries — Functionfind_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.
PeriodicGraphEmbeddings.SymmetryGroup3D — TypeSymmetryGroup3D{T} <: PeriodicGraphs.AbstractSymmetryGroupStore the information on the symmetry operations available on a PeriodicGraphEmbedding3D.
PeriodicGraphEmbeddings.PeriodicSymmetry3D — TypePeriodicSymmetry3D{T} <: PeriodicGraphs.AbstractSymmetrySingle symmetry of a PeriodicGraphEmbedding3D{T}.
See PeriodicGraphs.AbstractSymmetry for information on the API.
PeriodicGraphEmbeddings.SPACE_GROUP_HALL — ConstantDictionnary 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"
PeriodicGraphEmbeddings.SPACE_GROUP_HM — ConstantDictionnary mapping the HM symbol of a symmetry group to its Hall number.
In the keys, letters are lowercase and space is removed.
PeriodicGraphEmbeddings.SPACE_GROUP_FULL — ConstantDictionnary 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.
PeriodicGraphEmbeddings.SPACE_GROUP_IT — ConstantList mapping the International Table number of a symmetry group to its Hall number
PeriodicGraphEmbeddings.HALL_SYMBOLS — ConstantList of Hall symbols and crystal system corresponding to each Hall number
PeriodicGraphEmbeddings.find_hall_number — Functionfind_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.
PeriodicGraphEmbeddings.SpglibDataset — TypeSpglibDatasetWrapper 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}.
PeriodicGraphEmbeddings.get_symmetry_equivalents — Functionget_symmetry_equivalents([T=Rational{Int},] hall::Integer)The list of EquivalentPosition{T} corresponding to a symmetry group given by its Hall number.
Wrapper around spg_get_symmetry_from_database.
PeriodicGraphEmbeddings.get_spglib_dataset — Functionget_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.
PeriodicGraphEmbeddings.check_valid_symmetry — Functioncheck_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.
Settings
This document was generated with Documenter.jl version 0.27.25 on Tuesday 16 April 2024. Using Julia version 1.6.7.
PeriodicGraphEmbeddings provide the new type PeriodicGraphEmbedding which wraps:
PeriodicGraphCell 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 — TypePeriodicGraphEmbedding{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.
PeriodicGraphEmbeddings.PeriodicGraphEmbedding3D — TypePeriodicGraphEmbedding3DAlias for PeriodicGraphEmbedding{3}
PeriodicGraphEmbeddings.PeriodicGraphEmbedding — MethodPeriodicGraphEmbedding{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.
This function modifies the input graph if any element of placement is out of [0, 1).
To obtain a PeriodicGraphEmbedding with sorted positions, use SortedPeriodicGraphEmbedding instead
PeriodicGraphEmbeddings.SortedPeriodicGraphEmbedding — TypeSortedPeriodicGraphEmbedding{T}Constructor for PeriodicGraphEmbedding{D,T} where D with sorted positions.
PeriodicGraphEmbeddings.SortedPeriodicGraphEmbedding — MethodSortedPeriodicGraphEmbedding{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.
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).
SortedPeriodicGraphEmbedding(graph::PeriodicGraph{D}, placement::AbstractMatrix, cell::Cell=Cell()) where DBuild 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.
This function modifies the input graph if any element of placement is out of [0, 1).
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}.
PeriodicGraphEmbeddings.PeriodicGraphEmbedding — MethodPeriodicGraphEmbedding{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.
PeriodicGraphEmbeddings.Cell — TypeCell{T}Representation of a periodic cell in 3D. Contains information about the cell (axes lengths and angles) and its symmetry group, through its Hall number.
See PeriodicGraphEmbeddings.SPACE_GROUP_HALL, PeriodicGraphEmbeddings.SPACE_GROUP_FULL, PeriodicGraphEmbeddings.SPACE_GROUP_HM and PeriodicGraphEmbeddings.SPACE_GROUP_IT for the correspondance between Hall number and usual symbolic representations.
PeriodicGraphEmbeddings.cell_parameters — Functioncell_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.
PeriodicGraphEmbeddings.EquivalentPosition — TypeEquivalentPosition{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//2The type parameter T is the numeric type used to store the symmetry operations. It should be typically either Rational{Int} or Float64.
Missing docstring for Base.parse(::Type{EquivalentPosition}, s::AbstractString). Check Documenter's build log for details.
PeriodicGraphEmbeddings.find_refid — Functionfind_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").
Settings
This document was generated with Documenter.jl version 0.27.25 on Tuesday 16 April 2024. Using Julia version 1.6.7.
The periodic_distance function is useful to compute the shortest distance between two vertices of a graph of dimension 3 or less, i.e. for which a Cell has been provided. It assumes that the unit cell is not too much skewed.
PeriodicGraphEmbeddings.periodic_distance — Functionperiodic_distance(u, mat, ortho=nothing, safemin=nothing)Distance between point u and the origin, given as a triplet of fractional coordinates, in a repeating unit cell of matrix mat. The distance is the shortest between all equivalents of u and the origin. If ortho is set to true, the angles α, β and γ of the cell are assumed right, which accelerates the computation by up to 7 times. If a distance lower than safemin is computed, stop trying to find a periodic image of u closer to the origin. If unspecified, both ortho and safemin are automatically determined from mat.
This implementation assumes that the cell corresponds to a reduced lattice. It may be invalid for some edge cases otherwise.
For optimal performance, use periodic_distance! with buffer, ortho and safemin obtained from prepare_periodic_distance_computations.
PeriodicGraphEmbeddings.double_widen — Functiondouble_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.
Settings
This document was generated with Documenter.jl version 0.27.25 on Tuesday 16 April 2024. Using Julia version 1.6.7.