diff --git a/dev/faq/index.html b/dev/faq/index.html index bf357b8..f5a9452 100644 --- a/dev/faq/index.html +++ b/dev/faq/index.html @@ -34,4 +34,4 @@ julia> typeof(genome_allnodes) TopologicalGenome

In case where all clusterings lead to the same genome, it can simply be accessed by calling first(topo).

Having obtained a TopologicalGenome, the topological genome itself can accessed by converting it to a PeriodicGraph:

julia> genome = PeriodicGraph(genome_allnodes)
 PeriodicGraph3D(6, PeriodicEdge3D[(1, 2, (0,0,0)), (1, 3, (0,0,0)), (1, 4, (0,0,0)), (1, 4, (0,0,1)), (1, 5, (0,0,0)), (1, 6, (0,0,0)), (2, 4, (0,0,1)), (2, 6, (-1,0,0)), (3, 4, (0,0,1)), (3, 5, (0,-1,0)), (4, 5, (0,0,0)), (4, 6, (0,0,0))])

In case of error during topology identification, the returned genome is a PeriodicGraph{0}.

The string representation of the genome is simply string(genome):

julia> string(genome)
-"3 1 2 0 0 0 1 3 0 0 0 1 4 0 0 0 1 4 0 0 1 1 5 0 0 0 1 6 0 0 0 2 4 0 0 1 2 6 -1 0 0 3 4 0 0 1 3 5 0 -1 0 4 5 0 0 0 4 6 0 0 0"
+"3 1 2 0 0 0 1 3 0 0 0 1 4 0 0 0 1 4 0 0 1 1 5 0 0 0 1 6 0 0 0 2 4 0 0 1 2 6 -1 0 0 3 4 0 0 1 3 5 0 -1 0 4 5 0 0 0 4 6 0 0 0" diff --git a/dev/index.html b/dev/index.html index 9c3fac7..d7b1a0f 100644 --- a/dev/index.html +++ b/dev/index.html @@ -25,4 +25,4 @@ create_app(root, INSTALLATION_PATH; precompile_statements_file=abspath(root, "src", "precompile_statements.jl"), filter_stdlibs=true)

Compilation can take between fifteen minutes and an hour, depending on your hardware and the version of Julia.

The executable will be located in the "bin" subdirectory of the specified INSTALLATION_PATH, under the name "CrystalNets".

The executable can then simply be used on a chemical file:

$ CrystalNets /path/to/diamond.cif
-dia

Run CrystalNets --help for the list of options available to the executable.

Tip

In terms of performance, the compiled executable is the best option if you only want to identify a few structures from time to time. Using the website is recommended as well for this use-case, unless the nets you study are too big.

For intensive workloads with many structures to identify, it is best to use CrystalNets.jl as a Julia module through the determine_topology_dataset function. The module is also the best option to perform more advanced analyses on the net in Julia, or to use the Options unavailable to the executable.

+dia

Run CrystalNets --help for the list of options available to the executable.

Tip

In terms of performance, the compiled executable is the best option if you only want to identify a few structures from time to time. Using the website is recommended as well for this use-case, unless the nets you study are too big.

For intensive workloads with many structures to identify, it is best to use CrystalNets.jl as a Julia module through the determine_topology_dataset function. The module is also the best option to perform more advanced analyses on the net in Julia, or to use the Options unavailable to the executable.

diff --git a/dev/lib/internals/index.html b/dev/lib/internals/index.html index 1d88848..c0e1ce0 100644 --- a/dev/lib/internals/index.html +++ b/dev/lib/internals/index.html @@ -1,9 +1,9 @@ -Internals · CrystalNets.jl
Edit on GitHub

Internal types and functions

See also the documentations of PeriodicGraphs.jl and of PeriodicGraphEmbeddings.jl

Types

CrystalNets.Crystal — Type
Crystal

Intermediate representation of a crystal, retaining information on the cell, and the fractional placement of the atoms and their type, as well as the residues which will be used as vertices for the computation of the underlying topology.

source
CrystalNets.Clusters — Type
Clusters

Classification of the atoms of a crystalline framework in different clusters. For simple crystals, every atom is its own cluster. For a MOF, a cluster is a SBU, which can be either organic or inorganic.

source
CrystalNets.CollisionNode — Type
CollisionNode

Store the structure of a collision node through the subgraph g extracted with only the edges bond to the vertices in the node.

The num field corresponds to the number of vertices in g that collide in the initial graph, while the neighs field stores the indices of their neighbors out of the collision site.

The colliding vertices are the num first vertices of g, the others are the neighbors. In particular, nv(g) == num + length(neighs) and g[(num+1):(nv(g))] has no edge.

source

Core topology functions

CrystalNets.topological_key — Function
topological_key(net::CrystalNet)

Return a unique topological key for the net, which is a topological invariant of the net (i.e. it does not depend on its initial representation).

source
CrystalNets.minimize — Function
minimize(net::CrystalNet, [collisions::Vector{CollisionNode}])

Return a CrystalNet representing the same net as the input, but in a unit cell. If collisions is given, also return the corresponding collisions after minimization.

The computed unit cell may depend on the representation of the input, i.e. it is not topologicallly invariant.

source
minimize(net::Crystal{Nothing})

Return a Crystal representing the same crystal as the input, but in a unit cell.

source
CrystalNets.candidate_key — Function
candidate_key(net::CrystalNet, u, basis, minimal_edgs)

Given the net, a candidate u => basis where u is the origin and basis the triplet of axes, and minimal_edgs the last minimal key (for the pseudo-lexicographical order used), extract the key corresponding to the current candidate.

The key is the lexicographically ordered list of edges of the graph when its vertices are numbered according to the candidate. The ordering of keys first compares the list of edges disregarding the offsets, and then only compares the offsets if the rest is identical.

If the key is larger or equal to minimal_edgs, early stop and return two empty lists. Otherwise, the extracted key is the current best: return the vmap between the initial vertices and their ordered image in the candidate, as well as the key.

See also: find_candidates

source
CrystalNets.possible_translations — Function
possible_translations(c::Union{CrystalNet,CrystalNet})

Return a list of tuples (nz, i_max_den, max_den, t) where

  • t is a translation mapping at the origin vertex to another one in the unit cell.
  • max_den is the maximum denominator in the D coefficients of t.
  • i_max_den is the index.
  • nz is the number of zeros in t.

The list is guaranteed to contain all the possible valid translations but may contain some invalid translations.

See also: find_all_valid_translations, PeriodicGraphEmbeddings.check_valid_symmetry

source
CrystalNets.find_all_valid_translations — Function
find_all_valid_translations(c::Union{Crystal,CrystalNet{D}}, collisions) where D

Return a D-tuple of list of tuples (i_max_den, max_den, t) (see possible_translations for interpretation) where the n-th list contains all valid translations of the net having exactly n-1 zeros.

A translation is valid if it maps exactly each vertex to a vertex and each edge to an edge.

See also: possible_translations, PeriodicGraphEmbeddings.check_valid_symmetry

source
CrystalNets.reduce_with_matrix — Function
reduce_with_matrix(c::CrystalNet, mat, collisions)

Given the net and the output of minimal_volume_matrix computed on the valid translations of the net, return the new net representing the initial net in the computed unit cell.

source
CrystalNets.partition_by_coordination_sequence — Function
partition_by_coordination_sequence(graph, symmetries::AbstractSymmetryGroup=NoSymmetryGroup(graph))

Partition the vertices of the graph into disjoint categories, one for each coordination sequence. The partition is then sorted by order of coordination sequence. This partition does not depend on the representation of the graph. The optional argument vmaps is a set of permutations of the vertices that leave the graph unchanged. In other words, vmaps is a set of symmetry operations of the graph.

Return the categories and a list of unique representative for each symmetry class.

source
CrystalNets.find_candidates — Function
find_candidates(net::CrystalNet{D}, collisions::Vector{CollisionNode}) where D

Return a non-empty set of candidates u => basis where u is a vertex and basis is matrix whose columns are D linearly independent euclidean embeddings of edges. The returned set is independent of the representation of the graph used in net.

Also return a category_map linking each vertex to its category number, as defined by partition_by_coordination_sequence

See also: candidate_key

source
CrystalNets.extract_through_symmetry — Function
extract_through_symmetry(candidates::Dict{Int,Vector{SMatrix{3,3,T,9}}}, symmetries::AbstractSymmetryGroup) where T

Given the candidates and the list of symmetries of the net, return the flattened list of candidates after removing candidates that are symmetric images of the kept ones.

source
CrystalNets.find_initial_candidates — Function
find_initial_candidates(net::CrystalNet{D}, candidates_v, category_map) where D

Given the net, a list of vertices in a given category and the category_map, return a list of pairs u => (basis, cats) where u ∈ candidates_v, basis is a D-rank matrix made by juxtaposing the euclidean embeddings of outgoing edges from u, and cats are the categories of the respective neighbors of u.

If the basis corresponding to vertex u is not of rank D, it is not included in the returned list (for instance, if all outgoing edges of a vertex are coplanar with D == 3).

source
CrystalNets.find_candidates_onlyneighbors — Function
find_candidates_onlyneighbors(net::CrystalNet{D}, candidates_v, category_map) where D

Given the net, a list of vertices in a given category and the category_map, return a Dict whose pairs u => matv are such that u ∈ candidates_v and matv is a list of unique invertible matrices of size D whose columns are euclidean embeddings of outgoing edges from u. Each such matrix has a category, defined by the D-uplet of categories of each corresponding outneighbor of u: the returned Dict is such that all the matrices belonging to all matv share the same category.

The returned Dict is empty iff find_initial_candidates(net, candidates_v, category_map) is empty.

source

Input

CrystalNets.parse_cif — Function
parse_cif(file_path)

Parse a CIF file and return a dictionary where each identifier (without the starting '_' character) is linked to its value. Values are either a string or a vector of string (if defined in a loop).

source
CrystalNets.check_collision — Function
check_collision(pos, mat)

Given a list of fractional coordinates pos and the matrix of the unit cell mat, return a list of atoms that are suspiciously close to another atom of the list. For each collision site, only one atom is not present in the returned list.

source
CrystalNets.least_plausible_neighbours — Function
least_plausible_neighbours(Δs, n)

Find the positions of the n least probable neighbours of an atom, given the list Δs of the distance between their position and that of the atom.

This function is highly empirical and should not be considered utterly reliable.

source
CrystalNets.fix_valence! — Function
fix_valence!(graph::PeriodicGraph3D, pos, types, passH, passO, passCN, mat, ::Val{dofix}, options) where {dofix}

Attempt to ensure that the coordinence of certain atoms are at least plausible by removing some edges from the graph. These atoms are H, halogens, O, N and C. if dofix is set, actually modify the graph; otherwise, only emit a warning. In both cases, return a list of atoms with invalid coordinence.

source
CrystalNets.sanitize_removeatoms! — Function
sanitize_removeatoms!(graph::PeriodicGraph3D, pos, types, mat, options)

Special heuristics to remove atoms that seem to arise from an improper cleaning of the file. Currently implemented:

  • C atoms suspiciously close to metallic atoms.
  • One of two identical metallic atoms suspiciously close to one another

TODO:

  • O atoms with 4 coplanar bonds (warning only).
source
CrystalNets.remove_triangles! — Function
remove_triangles!(graph::PeriodicGraph3D, pos, types, mat, toinvestigate=collect(edges(graph)))

In a configuration where atoms A, B and C are pairwise bonded, remove the longest of the three bonds if it is suspicious (too large and too close to the third atom).

source
CrystalNets.remove_homoatomic_bonds! — Function
remove_homoatomic_bonds!(graph::PeriodicGraph, types, targets, reduce_homometallic)

Remove from the graph all bonds of the form X-X where X is an atom in targets.

Also remove all such bonds where X is a metal if the two bonded atoms up to third neighbours otherwise, and if reduce_homometallic is true.

source
CrystalNets.sanity_checks! — Function
sanity_checks!(graph, pos, types, mat, options)

Perform some sanity checks to ensure that the detected bonds are not obviously wrong because they are either too short or too long.

source

Crystal and CIF handling

CrystalNets.prune_collisions — Function
prune_collisions(::CIF)

For each site where there are atoms suspiciously close to one another, remove all but one of them. This arises for example when all the possible positions of at atom are superposed in the CIF file, typically for a solvent which should be disregarded anyway.

source
CrystalNets.trim_topology — Function
trim_topology(graph::PeriodicGraph)

Return a pair (vmap, newgraph) extracted from the input by removing vertices of valence lower or equal to 1, and by replacing vertices of valence 2 by edges, until convergence. The only exceptions are vertices only bonded to their representatives of another cell: those will not be replaced by edges even if their valence is 2, since this latter case indicates an irreducible trivial 1-dimensional topology.

vmap maps the vertices of newgraph to their counterpart in graph.

source

Bond guessing

CrystalNets.guess_bonds — Function
guess_bonds(pos, types, mat, options)

Return the bonds guessed from the positions, types and cell matrix, given as a Vector{Vector{Tuple{Int,Float32}}}.

The i-th entry of the list is a list, whose entries are of the form (j, dist) which indicates that the representatives of vertices i and j distant of at most dist are bonded together.

source
CrystalNets.edges_from_bonds — Function
edges_from_bonds(bonds::Vector{Vector{Tuple{Int,Float32}}}, mat, pos)

Given a bond list bonds containing triplets (a, b, dist) where atoms a and b are bonded if their distance is lower than dist, the 3×3 matrix of the cell mat and the Vector{SVector{3,Float64}} pos whose elements are the fractional positions of the atoms, extract the list of PeriodicEdge3D corresponding to the bonds. Since the adjacency matrix wraps bonds across the boundaries of the cell, the edges are extracted so that the closest representatives are chosen to form bonds.

source

Clustering algorithm

CrystalNets.find_sbus! — Function
find_sbus!(crystal::Crystal, kinds::ClusterKinds=default_sbus)

Recognize SBUs using heuristics based on the atom types corresponding to the AllNodes clustering algorithm.

source
CrystalNets.regroup_sbus — Function
regroup_sbus(graph::PeriodicGraph3D, classes::AbstractVector{<:Integer},
-             isolate=Int[])

Given a classification of vertices into classes, separate the vertices into clusters of contiguous vertices belonging to the same class.

isolate is a list where each atom is separated from the rest of its class. Once all such atoms of its class are isolated, we look for the connected components of non-isolated atoms in that class. If such a component has only one neighbours which is an isolated atom, it is added to the vertex of the isolated atom.

source
CrystalNets.regroup_paddlewheel! — Function
regroup_paddlewheel!(graph, clusters::Clusters, types, periodicsbus)

Identify paddle-wheel patterns made of two opposite SBUs and regroup them into one.

source
CrystalNets.split_sbu! — Function
split_sbu!(sbus, graph, i_sbu, classes)

Split SBU number i_sbu into new SBUs according to the updated classes. The first argument sbus is modified in-place. Return the list of newly-created periodic SBUs, if any.

source
CrystalNets.reclassify! — Function
reclassify!(sbus, newperiodicsbus, newclass, graph, types, classof, i_sbu)

Reclassify the atoms of sbus.sbus[i_sbu]) according to the following algorithm:

  • Let's call "target atom" any atom of type typ where classof[typ] == deg and either deg == 0 or deg > 0 and the degree of the atom is deg.
  • Assign a new SBU for each target atom (one new per atom).
  • Look at the connected components of atoms in the SBU which are not target atoms. For each connected component that is finite (0-dimensional) and has only one neighbor which is a target atom, put that component in the same SBU as the neighbor.
source
CrystalNets.add_to_newclass! — Function
add_to_newclass!(classes, graph, sbus, new_class, v, types, noneighborof)

Set the class of v to new_class. Then, grow the newly created class by adding connected components of the SBU of v such that the new class does not become periodic and does not contain any vertex that is a neighbor of a vertex whose type is in noneighborof.

If types === nothing, disregard the condition on noneighborof.

source
CrystalNets.group_cycle — Function
group_cycle(organiccycle, types, graph)

Return a list of Vector{PeriodicVertex3D} where each sublist consists in atoms belonging to the same cycle, and which should thus belong to the same vertex eventually.

source
CrystalNets.collapse_clusters — Function
collapse_clusters(crystal::Crystal)

Return the list of crystals corresponding to the input where each cluster has been transformed into a new vertex, for each targeted clustering.

source
CrystalNets.allnodes_to_singlenodes — Function
allnodes_to_singlenodes(cryst::Crystal)

Convert AllNodes result to SingleNodes by collapsing all points of extension clusters bonded together into a new organic cluster.

source

Unstable nets

CrystalNets.shrink_collisions — Function
shrink_collisions(net::CrystalNet, collisions)

Remove all colliding vertices and replace them by one new vertex per CollisionNode, whose neighbours are that of the vertices within.

source
CrystalNets.order_collision — Function
order_collision(graph::PeriodicGraph, colliding)

Given collision nodes (in the form of the corresponding list of colliding vertices), find an ordering of them which is independent of the current ordering of these vertices and of vertices which are neither in the collision node nor any of its neighbours. Return a this ordering and a priority list for each colliding vertex, or two empty lists if it fails.

This function assumes that no vertex in the node has a neighbour in another collision node and that there are no two representatives of the same vertex that are neighbour to some vertices in the range.

source
CrystalNets.expand_collisions — Function
expand_collisions(collisions::Vector{CollisionNode}, graph::PeriodicGraph, vmap)

Expand each collision node into the appropriate number of vertices so that the resulting graph is isomorphic to the initial one, in a manner that only depends on the current graph. Return the resulting graph.

vmap is the map of vertices between initial_graph (with collapsed collision nodes) and graph

Also return the permutations of nodes of graph prior to expansion.

source
CrystalNets.collision_nodes — Function
collision_nodes(c::CrystalNet)

Check that the net is stable, i.e. that no two vertices have the same equilibrium placement.

A net is still considered stable if the collisions in equilibrium placement cannot lead to different topological genomes. In practice, this happens when: A) there is no edge between two collision sites and B) there is no edge between a collision site and two representatives of the same vertex and C) for each collision site, the site is made of at most 4 vertices

In this case, return the CollisionNodeList with the corresponding CollisionNodes, the list being empty if the net is truly stable. Otherwise, return nothing.

Also return an updated net where the vertices in a CollisionNode are collapsed into a new vertex, appearing after the non-colliding vertices.

source

Archives

CrystalNets.make_archive — Function
make_archive(path, destination=nothing, verbose=false)

Make an archive from the files located in the directory given by path and export it to destination, if specified. Each file of the directory should correspond to a unique topology: if a topology is encountered multiple times, it will be assigned the name of the latest file that bore it.

The archive can then be used with change_current_archive!(destination; validate=false) for instance.

source

Utils

CrystalNets.@toggleassert — Macro
@toggleassert expression

Internal macro used to assert and expression conditionally on a build-time constant. To toggle on or off these assertions, the constant has to be modified in the source code and the module rebuilt afterwards.

source
CrystalNets.check_dimensionality — Function
check_dimensionality(c::CrystalNet)

Check that the dimensionality of the net (i.e. the number of independent axes along which it is periodic) is equal to D, or throw a DimensionMismatch otherwise.

source

Other

CrystalNets.guess_topology — Function
guess_topology(path, options::Options)
-guess_topology(path; kwargs...)

Tries to determine the topology of the file at path by passing various options (starting from the provided options if any) until finding a known topology. If none is found, return the topological genome encountered most often through the variation of options.

source
CrystalNets.guess_topology_dataset — Function
guess_topology_dataset(path, save, autoclean, showprogress, options::Options)
-guess_topology_dataset(path; save=true, autoclean=true, showprogress=true, kwargs...)

Given a path to a directory containing structure input files, guess the topology of each structure within the directory using guess_topology. Return a dictionary linking each file name to the result. The result is the corresponding topology name, if known, or the topological genome preceded by an "UNKNOWN" mention otherwise. In case of error, the result is the exception preceded by a "FAILED with" mention. Finally, if the input does not represent a periodic structure, the result is "0-dimensional".

It is strongly recommended to toggle warnings off (through toggle_warning) and not to export any file since those actions may critically reduce performance, especially for numerous files.

The save and autoclean arguments work identically to their counterpart for determine_topology_dataset.

If showprogress is set, a progress bar will be displayed representing the number of processed files.

source
CrystalNets.recognize_topology — Function
recognize_topology(g::PeriodicGraph, arc=CRYSTALNETS_ARCHIVE)
-recognize_topology(genome::AbstractString, arc=CRYSTALNETS_ARCHIVE)

Attempt to recognize a topological genome from an archive of known genomes.

Warning

This function does a simple lookup, not any kind of topology computation. To identify the topology of a PeriodicGraph or a CrystalNet x, query topological_genome(x) instead.

source
CrystalNets.total_interpenetration — Function
total_interpenetration(itr::InterpenetratedTopologyResult, clustering::Union{Nothing,_Clustering}=nothing)

Return a Dict{TopologicalGenome,Int} that links each topology to the number of interpenetrated nets having that topology (catenation included) for the given clustering. If clustering is nothing, all possible topologies will be studied.

Example

See InterpenetratedTopologyResult for reference on these examples.

julia> g = PeriodicGraph("2   1 1  0 2   2 2  0 1   2 2  1 0");
+Internals · CrystalNets.jl
Edit on GitHub
Internal types and functions
See also the documentations of PeriodicGraphs.jl and of PeriodicGraphEmbeddings.jl
Types
CrystalNets.Crystal — Type
Crystal
Intermediate representation of a crystal, retaining information on the cell, and the fractional placement of the atoms and their type, as well as the residues which will be used as vertices for the computation of the underlying topology.
source
CrystalNets.Clusters — Type
Clusters
Classification of the atoms of a crystalline framework in different clusters. For simple crystals, every atom is its own cluster. For a MOF, a cluster is a SBU, which can be either organic or inorganic.
source
CrystalNets.CollisionNode — Type
CollisionNode
Store the structure of a collision node through the subgraph g extracted with only the edges bond to the vertices in the node.
The num field corresponds to the number of vertices in g that collide in the initial graph, while the neighs field stores the indices of their neighbors out of the collision site.
The colliding vertices are the num first vertices of g, the others are the neighbors. In particular, nv(g) == num + length(neighs) and g[(num+1):(nv(g))] has no edge.
source
Core topology functions
CrystalNets.topological_key — Function
topological_key(net::CrystalNet)
Return a unique topological key for the net, which is a topological invariant of the net (i.e. it does not depend on its initial representation).
source
CrystalNets.minimize — Function
minimize(net::CrystalNet, [collisions::Vector{CollisionNode}])
Return a CrystalNet representing the same net as the input, but in a unit cell. If collisions is given, also return the corresponding collisions after minimization.
The computed unit cell may depend on the representation of the input, i.e. it is not topologicallly invariant.
source
minimize(net::Crystal{Nothing})
Return a Crystal representing the same crystal as the input, but in a unit cell.
source
CrystalNets.candidate_key — Function
candidate_key(net::CrystalNet, u, basis, minimal_edgs)
Given the net, a candidate u => basis where u is the origin and basis the triplet of axes, and minimal_edgs the last minimal key (for the pseudo-lexicographical order used), extract the key corresponding to the current candidate.
The key is the lexicographically ordered list of edges of the graph when its vertices are numbered according to the candidate. The ordering of keys first compares the list of edges disregarding the offsets, and then only compares the offsets if the rest is identical.
If the key is larger or equal to minimal_edgs, early stop and return two empty lists. Otherwise, the extracted key is the current best: return the vmap between the initial vertices and their ordered image in the candidate, as well as the key.
See also: find_candidates
source
CrystalNets.possible_translations — Function
possible_translations(c::Union{CrystalNet,CrystalNet})
Return a list of tuples (nz, i_max_den, max_den, t) where
  • t is a translation mapping at the origin vertex to another one in the unit cell.
  • max_den is the maximum denominator in the D coefficients of t.
  • i_max_den is the index.
  • nz is the number of zeros in t.
The list is guaranteed to contain all the possible valid translations but may contain some invalid translations.
See also: find_all_valid_translations, PeriodicGraphEmbeddings.check_valid_symmetry
source
CrystalNets.find_all_valid_translations — Function
find_all_valid_translations(c::Union{Crystal,CrystalNet{D}}, collisions) where D
Return a D-tuple of list of tuples (i_max_den, max_den, t) (see possible_translations for interpretation) where the n-th list contains all valid translations of the net having exactly n-1 zeros.
A translation is valid if it maps exactly each vertex to a vertex and each edge to an edge.
See also: possible_translations, PeriodicGraphEmbeddings.check_valid_symmetry
source
CrystalNets.reduce_with_matrix — Function
reduce_with_matrix(c::CrystalNet, mat, collisions)
Given the net and the output of minimal_volume_matrix computed on the valid translations of the net, return the new net representing the initial net in the computed unit cell.
source
CrystalNets.partition_by_coordination_sequence — Function
partition_by_coordination_sequence(graph, symmetries::AbstractSymmetryGroup=NoSymmetryGroup(graph))
Partition the vertices of the graph into disjoint categories, one for each coordination sequence. The partition is then sorted by order of coordination sequence. This partition does not depend on the representation of the graph. The optional argument vmaps is a set of permutations of the vertices that leave the graph unchanged. In other words, vmaps is a set of symmetry operations of the graph.
Return the categories and a list of unique representative for each symmetry class.
source
CrystalNets.find_candidates — Function
find_candidates(net::CrystalNet{D}, collisions::Vector{CollisionNode}) where D
Return a non-empty set of candidates u => basis where u is a vertex and basis is matrix whose columns are D linearly independent euclidean embeddings of edges. The returned set is independent of the representation of the graph used in net.
Also return a category_map linking each vertex to its category number, as defined by partition_by_coordination_sequence
See also: candidate_key
source
CrystalNets.extract_through_symmetry — Function
extract_through_symmetry(candidates::Dict{Int,Vector{SMatrix{3,3,T,9}}}, symmetries::AbstractSymmetryGroup) where T
Given the candidates and the list of symmetries of the net, return the flattened list of candidates after removing candidates that are symmetric images of the kept ones.
source
CrystalNets.find_initial_candidates — Function
find_initial_candidates(net::CrystalNet{D}, candidates_v, category_map) where D
Given the net, a list of vertices in a given category and the category_map, return a list of pairs u => (basis, cats) where u ∈ candidates_v, basis is a D-rank matrix made by juxtaposing the euclidean embeddings of outgoing edges from u, and cats are the categories of the respective neighbors of u.
If the basis corresponding to vertex u is not of rank D, it is not included in the returned list (for instance, if all outgoing edges of a vertex are coplanar with D == 3).
source
CrystalNets.find_candidates_onlyneighbors — Function
find_candidates_onlyneighbors(net::CrystalNet{D}, candidates_v, category_map) where D
Given the net, a list of vertices in a given category and the category_map, return a Dict whose pairs u => matv are such that u ∈ candidates_v and matv is a list of unique invertible matrices of size D whose columns are euclidean embeddings of outgoing edges from u. Each such matrix has a category, defined by the D-uplet of categories of each corresponding outneighbor of u: the returned Dict is such that all the matrices belonging to all matv share the same category.
The returned Dict is empty iff find_initial_candidates(net, candidates_v, category_map) is empty.
source
Input
CrystalNets.parse_cif — Function
parse_cif(file_path)
Parse a CIF file and return a dictionary where each identifier (without the starting '_' character) is linked to its value. Values are either a string or a vector of string (if defined in a loop).
source
CrystalNets.check_collision — Function
check_collision(pos, mat)
Given a list of fractional coordinates pos and the matrix of the unit cell mat, return a list of atoms that are suspiciously close to another atom of the list. For each collision site, only one atom is not present in the returned list.
source
CrystalNets.least_plausible_neighbours — Function
least_plausible_neighbours(Δs, n)
Find the positions of the n least probable neighbours of an atom, given the list Δs of the distance between their position and that of the atom.
This function is highly empirical and should not be considered utterly reliable.
source
CrystalNets.fix_valence! — Function
fix_valence!(graph::PeriodicGraph3D, pos, types, passH, passO, passCN, mat, ::Val{dofix}, options) where {dofix}
Attempt to ensure that the coordinence of certain atoms are at least plausible by removing some edges from the graph. These atoms are H, halogens, O, N and C. if dofix is set, actually modify the graph; otherwise, only emit a warning. In both cases, return a list of atoms with invalid coordinence.
source
CrystalNets.sanitize_removeatoms! — Function
sanitize_removeatoms!(graph::PeriodicGraph3D, pos, types, mat, options)
Special heuristics to remove atoms that seem to arise from an improper cleaning of the file. Currently implemented:
  • C atoms suspiciously close to metallic atoms.
  • One of two identical metallic atoms suspiciously close to one another
TODO:
  • O atoms with 4 coplanar bonds (warning only).
source
CrystalNets.remove_triangles! — Function
remove_triangles!(graph::PeriodicGraph3D, pos, types, mat, toinvestigate=collect(edges(graph)))
In a configuration where atoms A, B and C are pairwise bonded, remove the longest of the three bonds if it is suspicious (too large and too close to the third atom).
source
CrystalNets.remove_homoatomic_bonds! — Function
remove_homoatomic_bonds!(graph::PeriodicGraph, types, targets, reduce_homometallic)
Remove from the graph all bonds of the form X-X where X is an atom in targets.
Also remove all such bonds where X is a metal if the two bonded atoms up to third neighbours otherwise, and if reduce_homometallic is true.
source
CrystalNets.sanity_checks! — Function
sanity_checks!(graph, pos, types, mat, options)
Perform some sanity checks to ensure that the detected bonds are not obviously wrong because they are either too short or too long.
source
Crystal and CIF handling
CrystalNets.prune_collisions — Function
prune_collisions(::CIF)
For each site where there are atoms suspiciously close to one another, remove all but one of them. This arises for example when all the possible positions of at atom are superposed in the CIF file, typically for a solvent which should be disregarded anyway.
source
CrystalNets.trim_topology — Function
trim_topology(graph::PeriodicGraph)
Return a pair (vmap, newgraph) extracted from the input by removing vertices of valence lower or equal to 1, and by replacing vertices of valence 2 by edges, until convergence. The only exceptions are vertices only bonded to their representatives of another cell: those will not be replaced by edges even if their valence is 2, since this latter case indicates an irreducible trivial 1-dimensional topology.
vmap maps the vertices of newgraph to their counterpart in graph.
source
Bond guessing
CrystalNets.guess_bonds — Function
guess_bonds(pos, types, mat, options)
Return the bonds guessed from the positions, types and cell matrix, given as a Vector{Vector{Tuple{Int,Float32}}}.
The i-th entry of the list is a list, whose entries are of the form (j, dist) which indicates that the representatives of vertices i and j distant of at most dist are bonded together.
source
CrystalNets.edges_from_bonds — Function
edges_from_bonds(bonds::Vector{Vector{Tuple{Int,Float32}}}, mat, pos)
Given a bond list bonds containing triplets (a, b, dist) where atoms a and b are bonded if their distance is lower than dist, the 3×3 matrix of the cell mat and the Vector{SVector{3,Float64}} pos whose elements are the fractional positions of the atoms, extract the list of PeriodicEdge3D corresponding to the bonds. Since the adjacency matrix wraps bonds across the boundaries of the cell, the edges are extracted so that the closest representatives are chosen to form bonds.
source
Clustering algorithm
CrystalNets.find_sbus! — Function
find_sbus!(crystal::Crystal, kinds::ClusterKinds=default_sbus)
Recognize SBUs using heuristics based on the atom types corresponding to the AllNodes clustering algorithm.
source
CrystalNets.regroup_sbus — Function
regroup_sbus(graph::PeriodicGraph3D, classes::AbstractVector{<:Integer},
+             isolate=Int[])
Given a classification of vertices into classes, separate the vertices into clusters of contiguous vertices belonging to the same class.
isolate is a list where each atom is separated from the rest of its class. Once all such atoms of its class are isolated, we look for the connected components of non-isolated atoms in that class. If such a component has only one neighbours which is an isolated atom, it is added to the vertex of the isolated atom.
source
CrystalNets.regroup_paddlewheel! — Function
regroup_paddlewheel!(graph, clusters::Clusters, types, periodicsbus)
Identify paddle-wheel patterns made of two opposite SBUs and regroup them into one.
source
CrystalNets.split_sbu! — Function
split_sbu!(sbus, graph, i_sbu, classes)
Split SBU number i_sbu into new SBUs according to the updated classes. The first argument sbus is modified in-place. Return the list of newly-created periodic SBUs, if any.
source
CrystalNets.reclassify! — Function
reclassify!(sbus, newperiodicsbus, newclass, graph, types, classof, i_sbu)
Reclassify the atoms of sbus.sbus[i_sbu]) according to the following algorithm:
  • Let's call "target atom" any atom of type typ where classof[typ] == deg and either deg == 0 or deg > 0 and the degree of the atom is deg.
  • Assign a new SBU for each target atom (one new per atom).
  • Look at the connected components of atoms in the SBU which are not target atoms. For each connected component that is finite (0-dimensional) and has only one neighbor which is a target atom, put that component in the same SBU as the neighbor.
source
CrystalNets.add_to_newclass! — Function
add_to_newclass!(classes, graph, sbus, new_class, v, types, noneighborof)
Set the class of v to new_class. Then, grow the newly created class by adding connected components of the SBU of v such that the new class does not become periodic and does not contain any vertex that is a neighbor of a vertex whose type is in noneighborof.
If types === nothing, disregard the condition on noneighborof.
source
CrystalNets.group_cycle — Function
group_cycle(organiccycle, types, graph)
Return a list of Vector{PeriodicVertex3D} where each sublist consists in atoms belonging to the same cycle, and which should thus belong to the same vertex eventually.
source
CrystalNets.collapse_clusters — Function
collapse_clusters(crystal::Crystal)
Return the list of crystals corresponding to the input where each cluster has been transformed into a new vertex, for each targeted clustering.
source
CrystalNets.allnodes_to_singlenodes — Function
allnodes_to_singlenodes(cryst::Crystal)
Convert AllNodes result to SingleNodes by collapsing all points of extension clusters bonded together into a new organic cluster.
source
Unstable nets
CrystalNets.shrink_collisions — Function
shrink_collisions(net::CrystalNet, collisions)
Remove all colliding vertices and replace them by one new vertex per CollisionNode, whose neighbours are that of the vertices within.
source
CrystalNets.order_collision — Function
order_collision(graph::PeriodicGraph, colliding)
Given collision nodes (in the form of the corresponding list of colliding vertices), find an ordering of them which is independent of the current ordering of these vertices and of vertices which are neither in the collision node nor any of its neighbours. Return a this ordering and a priority list for each colliding vertex, or two empty lists if it fails.
This function assumes that no vertex in the node has a neighbour in another collision node and that there are no two representatives of the same vertex that are neighbour to some vertices in the range.
source
CrystalNets.expand_collisions — Function
expand_collisions(collisions::Vector{CollisionNode}, graph::PeriodicGraph, vmap)
Expand each collision node into the appropriate number of vertices so that the resulting graph is isomorphic to the initial one, in a manner that only depends on the current graph. Return the resulting graph.
vmap is the map of vertices between initial_graph (with collapsed collision nodes) and graph
Also return the permutations of nodes of graph prior to expansion.
source
CrystalNets.collision_nodes — Function
collision_nodes(c::CrystalNet)
Check that the net is stable, i.e. that no two vertices have the same equilibrium placement.
A net is still considered stable if the collisions in equilibrium placement cannot lead to different topological genomes. In practice, this happens when: A) there is no edge between two collision sites and B) there is no edge between a collision site and two representatives of the same vertex and C) for each collision site, the site is made of at most 4 vertices
In this case, return the CollisionNodeList with the corresponding CollisionNodes, the list being empty if the net is truly stable. Otherwise, return nothing.
Also return an updated net where the vertices in a CollisionNode are collapsed into a new vertex, appearing after the non-colliding vertices.
source
Archives
CrystalNets.make_archive — Function
make_archive(path, destination=nothing, verbose=false)
Make an archive from the files located in the directory given by path and export it to destination, if specified. Each file of the directory should correspond to a unique topology: if a topology is encountered multiple times, it will be assigned the name of the latest file that bore it.
The archive can then be used with change_current_archive!(destination; validate=false) for instance.
source
Utils
CrystalNets.@toggleassert — Macro
@toggleassert expression
Internal macro used to assert and expression conditionally on a build-time constant. To toggle on or off these assertions, the constant has to be modified in the source code and the module rebuilt afterwards.
source
CrystalNets.check_dimensionality — Function
check_dimensionality(c::CrystalNet)
Check that the dimensionality of the net (i.e. the number of independent axes along which it is periodic) is equal to D, or throw a DimensionMismatch otherwise.
source
Other
CrystalNets.guess_topology — Function
guess_topology(path, options::Options)
+guess_topology(path; kwargs...)
Tries to determine the topology of the file at path by passing various options (starting from the provided options if any) until finding a known topology. If none is found, return the topological genome encountered most often through the variation of options.
source
CrystalNets.guess_topology_dataset — Function
guess_topology_dataset(path, save, autoclean, showprogress, options::Options)
+guess_topology_dataset(path; save=true, autoclean=true, showprogress=true, kwargs...)
Given a path to a directory containing structure input files, guess the topology of each structure within the directory using guess_topology. Return a dictionary linking each file name to the result. The result is the corresponding topology name, if known, or the topological genome preceded by an "UNKNOWN" mention otherwise. In case of error, the result is the exception preceded by a "FAILED with" mention. Finally, if the input does not represent a periodic structure, the result is "0-dimensional".
It is strongly recommended to toggle warnings off (through toggle_warning) and not to export any file since those actions may critically reduce performance, especially for numerous files.
The save and autoclean arguments work identically to their counterpart for determine_topology_dataset.
If showprogress is set, a progress bar will be displayed representing the number of processed files.
source
CrystalNets.recognize_topology — Function
recognize_topology(g::PeriodicGraph, arc=CRYSTALNETS_ARCHIVE)
+recognize_topology(genome::AbstractString, arc=CRYSTALNETS_ARCHIVE)
Attempt to recognize a topological genome from an archive of known genomes.
Warning
This function does a simple lookup, not any kind of topology computation. To identify the topology of a PeriodicGraph or a CrystalNet x, query topological_genome(x) instead.
source
CrystalNets.total_interpenetration — Function
total_interpenetration(itr::InterpenetratedTopologyResult, clustering::Union{Nothing,_Clustering}=nothing)
Return a Dict{TopologicalGenome,Int} that links each topology to the number of interpenetrated nets having that topology (catenation included) for the given clustering. If clustering is nothing, all possible topologies will be studied.
Example
See InterpenetratedTopologyResult for reference on these examples.
julia> g = PeriodicGraph("2   1 1  0 2   2 2  0 1   2 2  1 0");
 
 julia> topologies1 = topological_genome(g)
 2 interpenetrated substructures:
@@ -29,4 +29,4 @@
 julia> CrystalNets.total_interpenetration(topologies2)
 Dict{TopologicalGenome, Int64} with 2 entries:
   pto      => 2
-  sqc11259 => 2
source

+  sqc11259 => 2
source
diff --git a/dev/lib/public/index.html b/dev/lib/public/index.html index 357bf94..d35014d 100644 --- a/dev/lib/public/index.html +++ b/dev/lib/public/index.html @@ -1,5 +1,5 @@ -Public · CrystalNets.jl
Edit on GitHub

API

Main types

CrystalNets.CrystalNet — Type
CrystalNet{D,T<:Real}

Representation of a net as a topological abstraction of a crystal.

D is the dimensionality of the net, which is the number of repeated dimensions of a single connex component. This dimensionality is not necessarily the dimension of the space the crystal is embedded into, which would always be 3 for real space.

T is the numeric type used to store the exact coordinates of each vertex at the equilibrium placement.

source
CrystalNets.TopologicalGenome — Type
TopologicalGenome

A topological genome computed by CrystalNets.jl.

Store both the actual genome (as a PeriodicGraph) and the name of the net, if recognized.

Like for a PeriodicGraph, the textual representation of a TopologicalGenome can be parsed back into a TopologicalGenome:

julia> topology = topological_genome(CrystalNet(PeriodicGraph("2  1 2 0 0  2 1 0 1  2 1 1 0")))
+Public · CrystalNets.jl
Edit on GitHub
API
Main types
CrystalNets.CrystalNet — Type
CrystalNet{D,T<:Real}
Representation of a net as a topological abstraction of a crystal.
D is the dimensionality of the net, which is the number of repeated dimensions of a single connex component. This dimensionality is not necessarily the dimension of the space the crystal is embedded into, which would always be 3 for real space.
T is the numeric type used to store the exact coordinates of each vertex at the equilibrium placement.
source
CrystalNets.TopologicalGenome — Type
TopologicalGenome
A topological genome computed by CrystalNets.jl.
Store both the actual genome (as a PeriodicGraph) and the name of the net, if recognized.
Like for a PeriodicGraph, the textual representation of a TopologicalGenome can be parsed back into a TopologicalGenome:
julia> topology = topological_genome(CrystalNet(PeriodicGraph("2  1 2 0 0  2 1 0 1  2 1 1 0")))
 hcb
 
 julia> typeof(topology)
@@ -9,7 +9,7 @@
 PeriodicGraph2D(2, PeriodicEdge2D[(1, 2, (-1,0)), (1, 2, (0,0)), (1, 2, (0,1))])
 
 julia> parse(TopologicalGenome, "hcb") == topology
-true
source
CrystalNets.TopologyResult — Type
TopologyResult
The result of a topology computation on a structure with different Clustering options.
Its representation includes the name of the clustering options along with their corresponding genome. It is omitted if there is only one clustering option which is Auto.
Like for a TopologicalGenome (or a PeriodicGraph), the textual representation of a TopologyResult can be parsed back to a TopologyResult:
julia> mof5 = joinpath(dirname(dirname(pathof(CrystalNets))), "test", "cif", "MOF-5.cif");
+true
source
CrystalNets.TopologyResult — Type
TopologyResult
The result of a topology computation on a structure with different Clustering options.
Its representation includes the name of the clustering options along with their corresponding genome. It is omitted if there is only one clustering option which is Auto.
Like for a TopologicalGenome (or a PeriodicGraph), the textual representation of a TopologyResult can be parsed back to a TopologyResult:
julia> mof5 = joinpath(dirname(dirname(pathof(CrystalNets))), "test", "cif", "MOF-5.cif");
 
 julia> topologies = only(determine_topology(mof5, structure=StructureType.MOF, clusterings=[Clustering.Auto, Clustering.Standard, Clustering.PE]))[1]
 AllNodes, SingleNodes: pcu
@@ -20,7 +20,7 @@
 TopologyResult
 
 julia> parse(TopologyResult, repr(topologies)) == topologies
-true
See also TopologicalGenome and InterpenetratedTopologyResult.
source
CrystalNets.InterpenetratedTopologyResult — Type
InterpenetratedTopologyResult <: AbstractVector{Tuple{TopologyResult,Int}}
The result of a topology computation on a structure containing possibly several interpenetrated substructures.
An InterpenetratedTopologyResult can be seen as a list of (topology, n) pair where
  • topology is the TopologyResult corresponding to the substructures.
  • n is an integer such that the substructure is composed of an n-fold catenated net.
The entire structure can thus be decomposed in a series of substructures, each of them possibly decomposed into several catenated nets.
Vocabulary
In this context, interpenetration and catenation have slightly different meanings:
  • two (or more) substructures are interpenetrated if both are present in the unit cell, and are composed of vertices that have disjoint numbers. They may or may not all have the same topology since they are disjoint and independent subgraphs. For example:
    julia> topological_genome(PeriodicGraph("2   1 1  0 1   2 2  0 1   2 2  1 0"))
+true
    See also TopologicalGenome and InterpenetratedTopologyResult.
source
CrystalNets.InterpenetratedTopologyResult — Type
InterpenetratedTopologyResult <: AbstractVector{Tuple{TopologyResult,Int}}
The result of a topology computation on a structure containing possibly several interpenetrated substructures.
An InterpenetratedTopologyResult can be seen as a list of (topology, n) pair where
  • topology is the TopologyResult corresponding to the substructures.
  • n is an integer such that the substructure is composed of an n-fold catenated net.
The entire structure can thus be decomposed in a series of substructures, each of them possibly decomposed into several catenated nets.
Vocabulary
In this context, interpenetration and catenation have slightly different meanings:
  • two (or more) substructures are interpenetrated if both are present in the unit cell, and are composed of vertices that have disjoint numbers. They may or may not all have the same topology since they are disjoint and independent subgraphs. For example:
    julia> topological_genome(PeriodicGraph("2   1 1  0 1   2 2  0 1   2 2  1 0"))
 2 interpenetrated substructures:
 ⋅ Subnet 1 → UNKNOWN 1 1 1 1
 ⋅ Subnet 2 → sql
  • a net is n-fold catenated if the unit cell of a single connected component of the net is n times larger than the unit cell of the overall net. In that case, the net is actually made of n interpenetrating connected components, which all have the same topology. For example:
    julia> topological_genome(PeriodicGraph("3   1 1  2 0 0   1 1  0 1 0   1 1  0 0 1"))
@@ -54,11 +54,11 @@
 PE: sqc11259
 
 julia> typeof(topology)
-TopologyResult
source
Main functions
CrystalNets.determine_topology — Function
determine_topology(path, options::Options)
-determine_topology(path; kwargs...)
Compute the topology of the structure described in the file located at path. This is exactly equivalent to calling topological_genome(UnderlyingNets(parse_chemfile(path, options))).
Return an InterpenetratedTopologyResult.
source
CrystalNets.determine_topology_dataset — Function
determine_topology_dataset(path, save, autoclean, showprogress, options::Options)
-determine_topology_dataset(path; save=true, autoclean=true, showprogress=true, kwargs...)
Given a path to a directory containing structure input files, compute the topology of each structure within the directory. Return a dictionary linking each file name to the result. The result is a InterpenetratedTopologyResult, containing the topological genome, the name if known and the stability of the net. In case of error, the exception is reported.
Warnings will be toggled off (unless force_warn is set) and it is stongly recommended not to export any file since those actions may critically reduce performance, especially for numerous files.
If save is set, the result is also stored in a julia serialized file located at "$path/../results_$i" where i is the lowest integer such that this path does not already exist at the start of the computation. While processing, this path will be used to create a directory storing the current state of the computation: to continue an interrupted computation, simply pass this temporary directory as the path. If autoclean is set, this directory is removed at the end if the computation was successful.
If save is set and autoclean is unset, the directory of temporary files will be renamed into "$path/../results_$i.OLD$j".
If showprogress is set, a progress bar will be displayed representing the number of processed files.
source
CrystalNets.parse_chemfile — Function
   parse_chemfile(path, options::Options)
-   parse_chemfile(path; kwargs...)
Parse a file given in any recognised chemical format and extract the topological information. Such format can be .cif or any file format recognised by Chemfiles.jl that contains all the necessary topological information.
source
CrystalNets.topological_genome — Function
topological_genome(net::CrystalNet{D,T})::String where {D,T}
Compute the topological genome of a net. The topological genome is an invariant if the net, meaning that it does not depend on its representation. It is also the string representation of a D-periodic graph such that PeriodicGraph{D}(topological_genome(net)) is isomorphic to net.pge.g (except possibly if the ignore_types option is unset).
Return a TopologicalGenome.
Info
Options must be passed directly within net.
source
topological_genome(g::Union{String,PeriodicGraph}, options::Options=Options())
-topological_genome(g::Union{String,PeriodicGraph}; kwargs...)
Compute the topological genome of a periodic graph. If given a topological key (as a string), it is converted to a PeriodicGraph first.
Return a TopologicalGenome.
source
topological_genome(group::UnderlyingNets)
Compute the topological genome of each subnet stored in group.
Return a InterpenetratedTopologyResult
Info
Options must be passed directly within the subnets.
source
Options
CrystalNets.Options — Type
Options
Different options, passed as keyword arguments.
Basic options
  • name: a name for the structure.
  • bonding: one of the Bonding options. Default is Bonding.Auto.
  • structure: one of the StructureType options. Default is StructureType.Auto.
  • clusterings: a list of Clustering options. Default is [Clustering.Auto].
Exports
For each export option, the accepted values are either a string, indicating the path to the directory in which to store the export, or a boolean, specifying whether or not to do the export. If the value is true, a path will be automatically determined. An empty string is equivalent to false.
  • export_input: the parsed structure, as a .vtf
  • export_trimmed: the parsed structure after iteratively removing all atoms having only one neighbour, as a .vtf
  • export_attributions: the attribution of vertices into SBUs, as a .pdb. Only relevant for the MOF StructureType.
  • export_clusters: the clustering of vertices, as a .vtf
  • export_net: the overall extracted net on which the topology is computed, as a .vtf.
  • export_subnets: each connected component of the overall net as a separate .vtf file. These subnets are defined after grouping vertices according to their Clustering.
Other options
  • ignore_atoms: set of atom symbols to ignore (for instance [:C,:H] will remove carbohydrate solvent residues).
  • ignore_types: disregard atom types to compute the topology, making pcu and pcu-b identical for example (default is true)
  • cutoff_coeff: coefficient used to detect bonds. Default is 0.75, higher values will include bonds that were considered too long before.
  • skip_minimize: assume that the cell is already the unit cell (default is false).
  • dimensions: the set of crystal net dimensions to consider. For instance, putting Set(3) will ensure that only 3-dimensional nets are considered. Default is Set([1,2,3]).
  • cluster_kinds: a ClusterKinds. Default separates organic and inorganic SBUs.
  • ignore_homoatomic_bonds: a Set{Symbol} such that all X-X bonds of the net are removed if X is an atom whose type is in ignore_homoatomic_bonds.
  • max_polyhedron_radius: an integer specifying the maximum number of bonds between two corners of the coordination polyhedron built for the Clustering.PE option. Default is 4.
  • Hbonds: set to true to include hydrogen bonds. Default is false.
  • Hbonds_dmax: the maximum length of a hydrogen bond. Only used if Hbonds is set. Default is 2.5 Å.
  • Hbonds_θmax: the maximum angle of a hydrogen bond. Only used if Hbonds is set. Default is 30°.
  • Hbonds_nmax: the maximum number of hydrogen bond per hydrogen. Only used if Hbonds is set. Default is 1.
Miscellaneous options
These boolean options have a default value that may be determined by Bonding, StructureType and Clustering. They can be directly overriden here.
  • bond_adjacent_sbus: bond together SBUs which are only separated by a single C atom.
  • authorize_pruning: remove colliding atoms in the input. Default is true.
  • wider_metallic_bonds: for bond detections, metals have a radius equal to 1.5× their Van der Waals radius. Default is false, unless StructureType is MOF or Zeolite.
  • ignore_homometallic_bonds: remove all bonds between two metal atoms of the same kind.
  • reduce_homometallic_bonds: when guessing bonds, do not bond two metallic atoms of the same type if they are up to third neighbours anyway. Default is false, unless StructureType is MOF.
  • ignore_metal_cluster_bonds: do not bond two metallic clusters together if they share at least one non-metallic neighbour. Default is false.
  • ignore_low_occupancy: atoms with occupancy lower than 0.5 are ignored. Default is false.
  • detect_paddlewheels: detect paddle-wheel pattern and group them into an inorganic vertex. Default is true.
  • detect_organiccycles: detect organic cycles and collapse all belonging C atoms into a new vertex. Default is true.
  • detect_pe: detect organic points-of-extension (organic atoms bonded to another SBU) and transform them into vertices. Default is true.
  • cluster_simple_pe: cluster adjacent points-of-extension if they are not part of a cycle. Default is true.
  • separate_metals: separate each metal atom into its own vertex (instead of grouping them to form metallic clusters if they are adjacent or bonded by an oxygen). Default is false, unless Clustering is Standard or PEM.
  • premerge_metalbonds: when a periodic metallic SBU is detected, cluster together bonded metal atoms of the same kind before splitting the SBU.
  • split_O_vertex: if a vertex is composed of a single O, remove it and bond together all of its neighbors, unless removing its hydrogen bonds would make it bivalent. Default is true.
  • unify_sbu_decomposition: apply the same rule to decompose both periodic and finite SBUs. Default is false.
  • force_warn: force printing warning and information even during ..._dataset function calls. Default is false.
  • label_for_type: use the atom label instead of its type. Default is false. Note that setting this to true will result in an error when detecting bonds if any atom has a label which is not an element of the periodic table.
Internal fields
These fields are for internal use and should not be modified by the user:
  • dryrun: store information on possible options to try (for guess_topology).
  • _pos: the positions of the centre of the clusters collapsed into vertices.
  • error: store the first error that occured when building the net.
  • throw_error: if set, throw the error instead of storing it in the error field.
  • track_mapping: if set to true, this field will contain, at the end of the computation, the mapping from the vertices of the input to the vertices of the returned genome. In the case of determine_topology... calls, the "input" is the file exported through the export_input option. Default is false.
source
CrystalNets.StructureType — Module
StructureType
Selection mode for the crystal structure. This choice impacts the bond detection algorithm as well as the clustering algorithm used.
The choices are:
  • Auto: No specific structure information. Use Van der Waals radii for bond detection and Input as Clustering, or EachVertex if the input does not provide residues.
  • MOF: Use Van der Waals radii for non-metallic atoms and larger radii for metals. Detect organic and inorganic clusters and subdivide them according to AllNodes and SingleNodes to identify underlying nets.
  • Cluster: similar to MOF but metallic atoms are not given a wider radius.
  • Zeolite: Same as Auto but use larger radii for metals (and metalloids) and attempt to enforce that each O atom has exactly two neighbours and that they are not O atoms.
  • Guess: try to identify the clusters as in Cluster. If it fails, fall back to Auto.
source
CrystalNets.Bonding — Module
Bonding
Selection mode for the detection of bonds. The choices are:
  • Input: use the input bonds. Fail if those are not specified.
  • Guess: guess bonds using a variant of chemfiles / VMD algorithm.
  • Auto: if the input specifies bonds, use them unless they look suspicious (too small or or too large according to a heuristic). Otherwise, fall back to Guess.
  • NoBond: do not guess or use any bond. This cannot be used to determine topology.
source
CrystalNets.Clustering — Module
Clustering
The clustering algorithm used to group atoms into vertices.
This choice only affects the creation of a UnderlyingNets from a Crystal, not the Crystal itself, and in particular not the bond detection algorithm.
The basic choices are:
  • Auto: determined using the StructureType.
  • Input: use the input residues as vertices. Fail if some atom does not belong to a residue.
  • EachVertex: each atom is its own vertex. Vertices with degree 2 or lower are iteratively collapsed into edges until all vertices have degree 3 or more.
The next clustering options are designed for MOFs but may target other kinds of frameworks. In all cases, the clusters are refinements on top of already-defined clusters, such as the organic and inorganic SBUs defined by the MOF structure. Except for AllNodes, infinite clusters (such as the inorganic clusters in a rod MOF) are split into new finite clusters using heuristics.
  • SingleNodes: each already-defined cluster is mapped to a vertex.
  • AllNodes: keep points of extension for organic clusters.
  • Standard: make each metallic atom its own vertex and do not bond those together if they share a common non-metallic neighbour.
  • PE: stands for Points of Extension. Keep points of extension for organic clusters, remove metallic centres and bond their surrounding points of extension.
  • PEM: stands for Points of Extension and Metals. Keep points of extension for organic clusters and each metal centre as a separate vertex.
source
CrystalNets.ClusterKinds — Type
ClusterKinds(sbus, toclassify=Int[])
Description of the different kinds of SBUs there should be when making clusters.
sbus should be a list of set of symbols, each set containing the different elements acceptable in this SBU (an empty set designates all remaining elements). All elements of the same category of the periodic table can be grouped together by putting the name of the category. For example, ClusterKinds([[:Au, :halogen, :nonmetal], [:metal, :metalloid], []]) means that there are three kinds of SBUs:
  • the first kind can only hold halogens, non-metals and Au atoms
  • the second kind can only hold metalloids and metals (except Au)
  • the third kind can hold all the other elements.
The list of possible categories is: :actinide, :noble (for noble gas), :halogen, :lanthanide, :metal, :metalloid and :nonmetal.
toclassify contains the list of SBUs which are not actual SBUs but only groups of atoms waiting to be merged to a neighboring SBU. The neighboring SBU is chosen by order in the sbus list.
The cluster kinds used by default are CrystalNets.ClusterKinds([[:metal, :actinide, :lanthanide], [:C,], [:P, :S],                            [:nonmetal, :metalloid, :halogen], [:noble]], [3, 4]). This means that all atoms that are either metals, actinides or lanthanides are assigned to class 1 and all C atoms in SBUs of class 2. Afterwards, each group of adjacent P or S atoms is assigned either class 1 if any of its neighbor is of class 1, or class 2 otherwise if any of its neighbor is of class 2. If no such neighbor exist, it is assigned to class 1. Finally, each group of adjacent nonmetals, metalloids and halogens is assigned class 1 or 2 following the same rule as for P and S atoms.
At the end of the procedure, all atoms are thus given a class between 1 and length(sbus) which is not in toclassify. See also find_sbus! for the implementation of this procedure.
To determine which SBU kind corresponds to a given atom, use getindex:
julia> sbu_kinds = CrystalNets.ClusterKinds([[:nonmetal, :halogen], [:metal, :F]]);
+TopologyResult
source
Main functions
CrystalNets.determine_topology — Function
determine_topology(path, options::Options)
+determine_topology(path; kwargs...)
Compute the topology of the structure described in the file located at path. This is exactly equivalent to calling topological_genome(UnderlyingNets(parse_chemfile(path, options))).
Return an InterpenetratedTopologyResult.
source
CrystalNets.determine_topology_dataset — Function
determine_topology_dataset(path, save, autoclean, showprogress, options::Options)
+determine_topology_dataset(path; save=true, autoclean=true, showprogress=true, kwargs...)
Given a path to a directory containing structure input files, compute the topology of each structure within the directory. Return a dictionary linking each file name to the result. The result is a InterpenetratedTopologyResult, containing the topological genome, the name if known and the stability of the net. In case of error, the exception is reported.
Warnings will be toggled off (unless force_warn is set) and it is stongly recommended not to export any file since those actions may critically reduce performance, especially for numerous files.
If save is set, the result is also stored in a julia serialized file located at "$path/../results_$i" where i is the lowest integer such that this path does not already exist at the start of the computation. While processing, this path will be used to create a directory storing the current state of the computation: to continue an interrupted computation, simply pass this temporary directory as the path. If autoclean is set, this directory is removed at the end if the computation was successful.
If save is set and autoclean is unset, the directory of temporary files will be renamed into "$path/../results_$i.OLD$j".
If showprogress is set, a progress bar will be displayed representing the number of processed files.
source
CrystalNets.parse_chemfile — Function
   parse_chemfile(path, options::Options)
+   parse_chemfile(path; kwargs...)
Parse a file given in any recognised chemical format and extract the topological information. Such format can be .cif or any file format recognised by Chemfiles.jl that contains all the necessary topological information.
source
CrystalNets.topological_genome — Function
topological_genome(net::CrystalNet{D,T})::String where {D,T}
Compute the topological genome of a net. The topological genome is an invariant if the net, meaning that it does not depend on its representation. It is also the string representation of a D-periodic graph such that PeriodicGraph{D}(topological_genome(net)) is isomorphic to net.pge.g (except possibly if the ignore_types option is unset).
Return a TopologicalGenome.
Info
Options must be passed directly within net.
source
topological_genome(g::Union{String,PeriodicGraph}, options::Options=Options())
+topological_genome(g::Union{String,PeriodicGraph}; kwargs...)
Compute the topological genome of a periodic graph. If given a topological key (as a string), it is converted to a PeriodicGraph first.
Return a TopologicalGenome.
source
topological_genome(group::UnderlyingNets)
Compute the topological genome of each subnet stored in group.
Return a InterpenetratedTopologyResult
Info
Options must be passed directly within the subnets.
source
Options
CrystalNets.Options — Type
Options
Different options, passed as keyword arguments.
Basic options
  • name: a name for the structure.
  • bonding: one of the Bonding options. Default is Bonding.Auto.
  • structure: one of the StructureType options. Default is StructureType.Auto.
  • clusterings: a list of Clustering options. Default is [Clustering.Auto].
Exports
For each export option, the accepted values are either a string, indicating the path to the directory in which to store the export, or a boolean, specifying whether or not to do the export. If the value is true, a path will be automatically determined. An empty string is equivalent to false.
  • export_input: the parsed structure, as a .vtf
  • export_trimmed: the parsed structure after iteratively removing all atoms having only one neighbour, as a .vtf
  • export_attributions: the attribution of vertices into SBUs, as a .pdb. Only relevant for the MOF StructureType.
  • export_clusters: the clustering of vertices, as a .vtf
  • export_net: the overall extracted net on which the topology is computed, as a .vtf.
  • export_subnets: each connected component of the overall net as a separate .vtf file. These subnets are defined after grouping vertices according to their Clustering.
Other options
  • ignore_atoms: set of atom symbols to ignore (for instance [:C,:H] will remove carbohydrate solvent residues).
  • ignore_types: disregard atom types to compute the topology, making pcu and pcu-b identical for example (default is true)
  • cutoff_coeff: coefficient used to detect bonds. Default is 0.75, higher values will include bonds that were considered too long before.
  • skip_minimize: assume that the cell is already the unit cell (default is false).
  • dimensions: the set of crystal net dimensions to consider. For instance, putting Set(3) will ensure that only 3-dimensional nets are considered. Default is Set([1,2,3]).
  • cluster_kinds: a ClusterKinds. Default separates organic and inorganic SBUs.
  • ignore_homoatomic_bonds: a Set{Symbol} such that all X-X bonds of the net are removed if X is an atom whose type is in ignore_homoatomic_bonds.
  • max_polyhedron_radius: an integer specifying the maximum number of bonds between two corners of the coordination polyhedron built for the Clustering.PE option. Default is 4.
  • Hbonds: set to true to include hydrogen bonds. Default is false.
  • Hbonds_dmax: the maximum length of a hydrogen bond. Only used if Hbonds is set. Default is 2.5 Å.
  • Hbonds_θmax: the maximum angle of a hydrogen bond. Only used if Hbonds is set. Default is 30°.
  • Hbonds_nmax: the maximum number of hydrogen bond per hydrogen. Only used if Hbonds is set. Default is 1.
Miscellaneous options
These boolean options have a default value that may be determined by Bonding, StructureType and Clustering. They can be directly overriden here.
  • bond_adjacent_sbus: bond together SBUs which are only separated by a single C atom.
  • authorize_pruning: remove colliding atoms in the input. Default is true.
  • wider_metallic_bonds: for bond detections, metals have a radius equal to 1.5× their Van der Waals radius. Default is false, unless StructureType is MOF or Zeolite.
  • ignore_homometallic_bonds: remove all bonds between two metal atoms of the same kind.
  • reduce_homometallic_bonds: when guessing bonds, do not bond two metallic atoms of the same type if they are up to third neighbours anyway. Default is false, unless StructureType is MOF.
  • ignore_metal_cluster_bonds: do not bond two metallic clusters together if they share at least one non-metallic neighbour. Default is false.
  • ignore_low_occupancy: atoms with occupancy lower than 0.5 are ignored. Default is false.
  • detect_paddlewheels: detect paddle-wheel pattern and group them into an inorganic vertex. Default is true.
  • detect_organiccycles: detect organic cycles and collapse all belonging C atoms into a new vertex. Default is true.
  • detect_pe: detect organic points-of-extension (organic atoms bonded to another SBU) and transform them into vertices. Default is true.
  • cluster_simple_pe: cluster adjacent points-of-extension if they are not part of a cycle. Default is true.
  • separate_metals: separate each metal atom into its own vertex (instead of grouping them to form metallic clusters if they are adjacent or bonded by an oxygen). Default is false, unless Clustering is Standard or PEM.
  • premerge_metalbonds: when a periodic metallic SBU is detected, cluster together bonded metal atoms of the same kind before splitting the SBU.
  • split_O_vertex: if a vertex is composed of a single O, remove it and bond together all of its neighbors, unless removing its hydrogen bonds would make it bivalent. Default is true.
  • unify_sbu_decomposition: apply the same rule to decompose both periodic and finite SBUs. Default is false.
  • force_warn: force printing warning and information even during ..._dataset function calls. Default is false.
  • label_for_type: use the atom label instead of its type. Default is false. Note that setting this to true will result in an error when detecting bonds if any atom has a label which is not an element of the periodic table.
Internal fields
These fields are for internal use and should not be modified by the user:
  • dryrun: store information on possible options to try (for guess_topology).
  • _pos: the positions of the centre of the clusters collapsed into vertices.
  • error: store the first error that occured when building the net.
  • throw_error: if set, throw the error instead of storing it in the error field.
  • track_mapping: if set to true, this field will contain, at the end of the computation, the mapping from the vertices of the input to the vertices of the returned genome. In the case of determine_topology... calls, the "input" is the file exported through the export_input option. Default is false.
source
CrystalNets.StructureType — Module
StructureType
Selection mode for the crystal structure. This choice impacts the bond detection algorithm as well as the clustering algorithm used.
The choices are:
  • Auto: No specific structure information. Use Van der Waals radii for bond detection and Input as Clustering, or EachVertex if the input does not provide residues.
  • MOF: Use Van der Waals radii for non-metallic atoms and larger radii for metals. Detect organic and inorganic clusters and subdivide them according to AllNodes and SingleNodes to identify underlying nets.
  • Cluster: similar to MOF but metallic atoms are not given a wider radius.
  • Zeolite: Same as Auto but use larger radii for metals (and metalloids) and attempt to enforce that each O atom has exactly two neighbours and that they are not O atoms.
  • Guess: try to identify the clusters as in Cluster. If it fails, fall back to Auto.
source
CrystalNets.Bonding — Module
Bonding
Selection mode for the detection of bonds. The choices are:
  • Input: use the input bonds. Fail if those are not specified.
  • Guess: guess bonds using a variant of chemfiles / VMD algorithm.
  • Auto: if the input specifies bonds, use them unless they look suspicious (too small or or too large according to a heuristic). Otherwise, fall back to Guess.
  • NoBond: do not guess or use any bond. This cannot be used to determine topology.
source
CrystalNets.Clustering — Module
Clustering
The clustering algorithm used to group atoms into vertices.
This choice only affects the creation of a UnderlyingNets from a Crystal, not the Crystal itself, and in particular not the bond detection algorithm.
The basic choices are:
  • Auto: determined using the StructureType.
  • Input: use the input residues as vertices. Fail if some atom does not belong to a residue.
  • EachVertex: each atom is its own vertex. Vertices with degree 2 or lower are iteratively collapsed into edges until all vertices have degree 3 or more.
The next clustering options are designed for MOFs but may target other kinds of frameworks. In all cases, the clusters are refinements on top of already-defined clusters, such as the organic and inorganic SBUs defined by the MOF structure. Except for AllNodes, infinite clusters (such as the inorganic clusters in a rod MOF) are split into new finite clusters using heuristics.
  • SingleNodes: each already-defined cluster is mapped to a vertex.
  • AllNodes: keep points of extension for organic clusters.
  • Standard: make each metallic atom its own vertex and do not bond those together if they share a common non-metallic neighbour.
  • PE: stands for Points of Extension. Keep points of extension for organic clusters, remove metallic centres and bond their surrounding points of extension.
  • PEM: stands for Points of Extension and Metals. Keep points of extension for organic clusters and each metal centre as a separate vertex.
source
CrystalNets.ClusterKinds — Type
ClusterKinds(sbus, toclassify=Int[])
Description of the different kinds of SBUs there should be when making clusters.
sbus should be a list of set of symbols, each set containing the different elements acceptable in this SBU (an empty set designates all remaining elements). All elements of the same category of the periodic table can be grouped together by putting the name of the category. For example, ClusterKinds([[:Au, :halogen, :nonmetal], [:metal, :metalloid], []]) means that there are three kinds of SBUs:
  • the first kind can only hold halogens, non-metals and Au atoms
  • the second kind can only hold metalloids and metals (except Au)
  • the third kind can hold all the other elements.
The list of possible categories is: :actinide, :noble (for noble gas), :halogen, :lanthanide, :metal, :metalloid and :nonmetal.
toclassify contains the list of SBUs which are not actual SBUs but only groups of atoms waiting to be merged to a neighboring SBU. The neighboring SBU is chosen by order in the sbus list.
The cluster kinds used by default are CrystalNets.ClusterKinds([[:metal, :actinide, :lanthanide], [:C,], [:P, :S],                            [:nonmetal, :metalloid, :halogen], [:noble]], [3, 4]). This means that all atoms that are either metals, actinides or lanthanides are assigned to class 1 and all C atoms in SBUs of class 2. Afterwards, each group of adjacent P or S atoms is assigned either class 1 if any of its neighbor is of class 1, or class 2 otherwise if any of its neighbor is of class 2. If no such neighbor exist, it is assigned to class 1. Finally, each group of adjacent nonmetals, metalloids and halogens is assigned class 1 or 2 following the same rule as for P and S atoms.
At the end of the procedure, all atoms are thus given a class between 1 and length(sbus) which is not in toclassify. See also find_sbus! for the implementation of this procedure.
To determine which SBU kind corresponds to a given atom, use getindex:
julia> sbu_kinds = CrystalNets.ClusterKinds([[:nonmetal, :halogen], [:metal, :F]]);
 
 julia> sbu_kinds[:O] # nonmetal
 1
@@ -70,7 +70,7 @@
 2
 
 julia> sbu_kinds[:Ne] # no given SBU kind
-0
If no empty set has been explicitly added to sbus and an element falls outside of the included categories, the returned SBU kind is 0.
An exception is made for nonmetals which are part of an aromatic heterocycle: those will be treated separately and put in the SBU of the corresponding carbons.
source
Other utilities
CrystalNets.toggle_warning — Function
toggle_warning(to=nothing)
Toggle warnings on (if to == true) or off (if to == false). Without an argument, toggle on and off repeatedly at each call.
source
CrystalNets.toggle_export — Function
toggle_export(to=nothing)
Toggle default exports on (if to == true) or off (if to == false). Without an argument, toggle on and off repeatedly at each call.
source
CrystalNets.export_default — Function
export_default(c::Union{PeriodicGraph,CrystalNet,Crystal}, obj=nothing, name=nothing, path=tempdir(); repeats=nothing)
Export a VTF representation of an object at the given path.
obj is a String describing the nature of the object, such as "net", "clusters" or "subnet" for example. Default is string(typeof(c)).
name is a String inserted in the exported file name. Default is a tempname.
repeats is the maximum distance between a represented atom out of the unit cell and one inside. Default is between 2 and 6, depending on obj and the size of the graph.
source
Archive
CrystalNets.REVERSE_CRYSTALNETS_ARCHIVE — Constant
const REVERSE_CRYSTALNETS_ARCHIVE::Dict{String,String}
Reverse of CRYSTALNETS_ARCHIVE.
Can be used to query the topological genome of known nets, as in:
julia> REVERSE_CRYSTALNETS_ARCHIVE["dia"]
+0
If no empty set has been explicitly added to sbus and an element falls outside of the included categories, the returned SBU kind is 0.
An exception is made for nonmetals which are part of an aromatic heterocycle: those will be treated separately and put in the SBU of the corresponding carbons.
source
Other utilities
CrystalNets.toggle_warning — Function
toggle_warning(to=nothing)
Toggle warnings on (if to == true) or off (if to == false). Without an argument, toggle on and off repeatedly at each call.
source
CrystalNets.toggle_export — Function
toggle_export(to=nothing)
Toggle default exports on (if to == true) or off (if to == false). Without an argument, toggle on and off repeatedly at each call.
source
CrystalNets.export_default — Function
export_default(c::Union{PeriodicGraph,CrystalNet,Crystal}, obj=nothing, name=nothing, path=tempdir(); repeats=nothing)
Export a VTF representation of an object at the given path.
obj is a String describing the nature of the object, such as "net", "clusters" or "subnet" for example. Default is string(typeof(c)).
name is a String inserted in the exported file name. Default is a tempname.
repeats is the maximum distance between a represented atom out of the unit cell and one inside. Default is between 2 and 6, depending on obj and the size of the graph.
source
Archive
CrystalNets.REVERSE_CRYSTALNETS_ARCHIVE — Constant
const REVERSE_CRYSTALNETS_ARCHIVE::Dict{String,String}
Reverse of CRYSTALNETS_ARCHIVE.
Can be used to query the topological genome of known nets, as in:
julia> REVERSE_CRYSTALNETS_ARCHIVE["dia"]
 "3 1 2 0 0 0 1 2 0 0 1 1 2 0 1 0 1 2 1 0 0"
 
 julia> topological_genome(CrystalNet(PeriodicGraph(ans)))
@@ -78,4 +78,4 @@
 PeriodicGraph3D(1, PeriodicEdge3D[(1, 1, (0,0,1)), (1, 1, (0,1,0)), (1, 1, (1,0,0))])
 
 julia> string(PeriodicGraph(parse(TopologicalGenome, "nbo"))) == REVERSE_CRYSTALNETS_ARCHIVE["nbo"]
-true
source
CrystalNets.parse_arc — Function
parse_arc(file)

Parse a .arc Systre archive such as the one used by the RCSR. Return a pair (flag, pairs).

flag is set if the archive corresponds to one generated by a compatible release of CrystalNets. If unset, the genomes of the archive may not be the same as those computed by CrystalNets for the same nets. pairs is a Dict{String,String} whose entries have the form genome => id where id is the name of the net and genome is the topological genome corresponding to this net (given as a string of whitespace-separated values parseable by PeriodicGraph).

source
CrystalNets.parse_arcs — Function
parse_arcs(file)

Parse a folder containing .arc Systre archives such as the one used by the RCSR. Return a pair (flag, pairs) with the same convention than parse_arc.

source
CrystalNets.clean_default_archive! — Function
clean_default_archive!(custom_arc; validate=true, refresh=true)

Erase the default archive used by CrystalNets.jl to recognize known topologies and replace it with a new one from the file located at custom_arc.

The validate parameter controls whether the new file is checked and converted to a format usable by CrystalNets.jl. If unsure, leave it set.

The refresh optional parameter controls whether the current archive should be replaced by the new default one.

Warning

This archive will be kept and used for subsequent runs of CrystalNets.jl, even if you restart your Julia session.

To only change the archive for the current session, use change_current_archive!(custom_arc).

See also refresh_current_archive! for similar uses.

Warning

The previous default archive cannot be recovered afterwards, so make sure to keep a copy if necessary. The default archive is the set of ".arc" files located at joinpath(dirname(dirname(pathof(CrystalNets))), "archives").

source
CrystalNets.set_default_archive! — Function
set_default_archive!()

Set the current archive as the new default archive.

Warning

This archive will be kept and used for subsequent runs of CrystalNets.jl, even if you restart your Julia session.

source
CrystalNets.empty_default_archive! — Function
empty_default_archive!(; refresh=true)

Empty the default archive. This will prevent CrystalNets from recognizing any topology before they are explicitly added.

The refresh optional parameter controls whether the current archive should also be emptied.

Warning

This empty archive will be kept and used for subsequent runs of CrystalNets.jl, even if you restart your Julia session. If you only want to empty the current archive, do empty!(CrystalNets.CRYSTALNETS_ARCHIVE).

source
CrystalNets.change_current_archive! — Function
change_current_archive!(custom_arc; validate=true)

Erase the current archive used by CrystalNets.jl to recognize known topologies and replace it with the archive stored in the file located at custom_arc.

The validate optional parameter controls whether the new file is checked and converted to a format usable by CrystalNets.jl. If unsure, leave it set.

Note

This modification will only last for the duration of this Julia session.

If you wish to change the default archive and use it for subsequent runs, use clean_default_archive!.

Warning

Using an invalid archive will make CrystalNets.jl unusable. If this happens, simply run refresh_current_archive!() to revert to the default archive.

source
CrystalNets.add_to_current_archive! — Function
add_to_current_archive!(id, genome)

Mark genome as the topological genome associated with the name id in the current archive.

The input id and genome are not modified by this operation.

Note

This modification will only last for the duration of this Julia session.

If you wish to save the archive and use it for subsequent runs, use set_default_archive! after calling this function.

source
CrystalNets.export_arc — Function
export_arc(path, arc=CRYSTALNETS_ARCHIVE)

Export archive arc to the specified path. If unspecified, the exported archive is the current one.

source
+truesource
CrystalNets.parse_arc — Function
parse_arc(file)

Parse a .arc Systre archive such as the one used by the RCSR. Return a pair (flag, pairs).

flag is set if the archive corresponds to one generated by a compatible release of CrystalNets. If unset, the genomes of the archive may not be the same as those computed by CrystalNets for the same nets. pairs is a Dict{String,String} whose entries have the form genome => id where id is the name of the net and genome is the topological genome corresponding to this net (given as a string of whitespace-separated values parseable by PeriodicGraph).

source
CrystalNets.parse_arcs — Function
parse_arcs(file)

Parse a folder containing .arc Systre archives such as the one used by the RCSR. Return a pair (flag, pairs) with the same convention than parse_arc.

source
CrystalNets.clean_default_archive! — Function
clean_default_archive!(custom_arc; validate=true, refresh=true)

Erase the default archive used by CrystalNets.jl to recognize known topologies and replace it with a new one from the file located at custom_arc.

The validate parameter controls whether the new file is checked and converted to a format usable by CrystalNets.jl. If unsure, leave it set.

The refresh optional parameter controls whether the current archive should be replaced by the new default one.

Warning

This archive will be kept and used for subsequent runs of CrystalNets.jl, even if you restart your Julia session.

To only change the archive for the current session, use change_current_archive!(custom_arc).

See also refresh_current_archive! for similar uses.

Warning

The previous default archive cannot be recovered afterwards, so make sure to keep a copy if necessary. The default archive is the set of ".arc" files located at joinpath(dirname(dirname(pathof(CrystalNets))), "archives").

source
CrystalNets.set_default_archive! — Function
set_default_archive!()

Set the current archive as the new default archive.

Warning

This archive will be kept and used for subsequent runs of CrystalNets.jl, even if you restart your Julia session.

source
CrystalNets.empty_default_archive! — Function
empty_default_archive!(; refresh=true)

Empty the default archive. This will prevent CrystalNets from recognizing any topology before they are explicitly added.

The refresh optional parameter controls whether the current archive should also be emptied.

Warning

This empty archive will be kept and used for subsequent runs of CrystalNets.jl, even if you restart your Julia session. If you only want to empty the current archive, do empty!(CrystalNets.CRYSTALNETS_ARCHIVE).

source
CrystalNets.change_current_archive! — Function
change_current_archive!(custom_arc; validate=true)

Erase the current archive used by CrystalNets.jl to recognize known topologies and replace it with the archive stored in the file located at custom_arc.

The validate optional parameter controls whether the new file is checked and converted to a format usable by CrystalNets.jl. If unsure, leave it set.

Note

This modification will only last for the duration of this Julia session.

If you wish to change the default archive and use it for subsequent runs, use clean_default_archive!.

Warning

Using an invalid archive will make CrystalNets.jl unusable. If this happens, simply run refresh_current_archive!() to revert to the default archive.

source
CrystalNets.refresh_current_archive! — Function
refresh_current_archive!()

Revert the current topological archive to the default one.

source
CrystalNets.add_to_current_archive! — Function
add_to_current_archive!(id, genome)

Mark genome as the topological genome associated with the name id in the current archive.

The input id and genome are not modified by this operation.

Note

This modification will only last for the duration of this Julia session.

If you wish to save the archive and use it for subsequent runs, use set_default_archive! after calling this function.

source
CrystalNets.export_arc — Function
export_arc(path, arc=CRYSTALNETS_ARCHIVE)

Export archive arc to the specified path. If unspecified, the exported archive is the current one.

source
diff --git a/dev/python/index.html b/dev/python/index.html index be4054a..811189b 100644 --- a/dev/python/index.html +++ b/dev/python/index.html @@ -46,4 +46,4 @@ File "<stdin>", line 1, in <module> File "<stdin>", line 11, in identify_topology File "<stdin>", line 5, in check_unique_topology -Exception: SingleNodes result bpq != AllNodes result rna +Exception: SingleNodes result bpq != AllNodes result rna diff --git a/dev/search/index.html b/dev/search/index.html index 0f6ee48..5e59c8d 100644 --- a/dev/search/index.html +++ b/dev/search/index.html @@ -1,2 +1,2 @@ -Search · CrystalNets.jl

Loading search...

    +Search · CrystalNets.jl

    Loading search...

      diff --git a/dev/visualization/index.html b/dev/visualization/index.html index 3e49ed6..d1fd355 100644 --- a/dev/visualization/index.html +++ b/dev/visualization/index.html @@ -41,4 +41,4 @@ Export of subnet_SingleNodes is enabled: saving file at /tmp/subnet_SingleNodes_IM-19_1.vtf AllNodes: rna SingleNodes: bpq

      Although not necessary, we manually specified bonding=Bonding.Guess to avoid the following warning

      [ Warning: Guessing bonds with custom algorithm (from Chemfiles and VMD). This may take a while for big structures and may be inexact.
-[ Info: To avoid guessing bonds, use a file format that contains the bonds.

      The first line of the output is an information about atoms with initial number of bonds. Note that there is no subsequent warning of the form

      [ Warning: After attempted fix, found remaining C with invalid number of bonds.

      which indicates that the problem has been internally resolved. It might be good to manually check whether the guessed bonds make sense, as an extra precaution.

      To do so, simply open VMD and load the VTF file corresponding to the input. On Ubuntu, the following shell command can be used:

      vmd /tmp/input_IM-19_0.vtf

      The result will look like this: IM-19 visualization in VMD

      To visualize the "single nodes" clusters on top of the input, navigate to File -> New Molecule... in the VMD window and load the adequate VTF file (in our case, the one located at /tmp/subnet_SingleNodes_IM-19_0.vtf). The result should look like this: IM-19 with single nodes clusters superposed

      To look at the underlying topology only (in our case, the bpq net), you can toggle off the visualization of the input file by double-clicking on the D letter left to the input file name in the main VMD window. The result should look like this: bpq net underlying IM-19

      Export options

      There are several export options bundled with CrystalNets.jl, documented in the Options. Each of them can be given as keyword arguments to all functions accepting an Options argument, like determine_topology.

      The value of the keyword argument can be either:

      The two exports whose default value is defined by CrystalNets.toggle_export are:

      Other available export options are disabled by default:

      +[ Info: To avoid guessing bonds, use a file format that contains the bonds.

      The first line of the output is an information about atoms with initial number of bonds. Note that there is no subsequent warning of the form

      [ Warning: After attempted fix, found remaining C with invalid number of bonds.

      which indicates that the problem has been internally resolved. It might be good to manually check whether the guessed bonds make sense, as an extra precaution.

      To do so, simply open VMD and load the VTF file corresponding to the input. On Ubuntu, the following shell command can be used:

      vmd /tmp/input_IM-19_0.vtf

      The result will look like this: IM-19 visualization in VMD

      To visualize the "single nodes" clusters on top of the input, navigate to File -> New Molecule... in the VMD window and load the adequate VTF file (in our case, the one located at /tmp/subnet_SingleNodes_IM-19_0.vtf). The result should look like this: IM-19 with single nodes clusters superposed

      To look at the underlying topology only (in our case, the bpq net), you can toggle off the visualization of the input file by double-clicking on the D letter left to the input file name in the main VMD window. The result should look like this: bpq net underlying IM-19

      Export options

      There are several export options bundled with CrystalNets.jl, documented in the Options. Each of them can be given as keyword arguments to all functions accepting an Options argument, like determine_topology.

      The value of the keyword argument can be either:

      The two exports whose default value is defined by CrystalNets.toggle_export are:

      Other available export options are disabled by default: