1+ """
2+ generators(num::Integer, T::Type{AbstractGroup{D}}[, optargs])
3+ generators(pgiuc::String, T::PointGroup{D}}) --> Vector{SymOperation{D}}
4+
5+ Return the generators of the group type `T` which may be a `SpaceGroup{D}` or a
6+ `PointGroup{D}` parameterized by its dimensionality `D`. Depending on `T`, the group is
7+ determined by inputting as the first argument:
8+
9+ - `SpaceGroup{D}`: the space group number `num::Integer`.
10+ - `PointGroup{D}`: the point group IUC label `pgiuc::String` (see also
11+ [`pointgroup(::String)`) or the canonical point group number `num::Integer`, which can
12+ optionally be supplemented by an integer-valued setting choice `setting::Integer` (see
13+ also [`pointgroup(::Integer, ::Integer, ::Integer)`](@ref)]).
14+ - `SubperiodicGroup{D}`: the subperiodic group number `num::Integer`.
15+
16+ Setting choices match those in [`spacegroup`](@ref), [`pointgroup`](@ref), and
17+ [`subperiodicgroup`](@ref).
18+
19+ Iterated composition of the returned symmetry operations will generate all operations of the
20+ associated space or point group (see [`generate`](@ref)).
21+ As an example, `generate(generators(num, `SpaceGroup{D}))` and `spacegroup(num, D)` return
22+ identical operations (with different sorting typically); and similarly so for point and
23+ subperiodic groups.
24+
25+ ## Example
26+
27+ Generators of space group 200:
28+ ```jldoctest
29+ julia> generators(200, SpaceGroup{3})
30+ 4-element Vector{SymOperation{3}}:
31+ 2₀₀₁
32+ 2₀₁₀
33+ 3₁₁₁⁺
34+ -1
35+ ```
36+
37+ Generators of point group m-3m:
38+ ```jldoctest
39+ julia> generators("2/m", PointGroup{3})
40+ 2-element Vector{SymOperation{3}}:
41+ 2₀₁₀
42+ -1
43+ ```
44+
45+ Generators of the Frieze group 𝓅2mg:
46+ ```jldoctest
47+ julia> generators(7, SubperiodicGroup{2, 1})
48+ 2-element Vector{SymOperation{2}}:
49+ 2
50+ {m₁₀|½,0}
51+ ```
52+
53+ ## Citing
54+
55+ Please cite the original data sources if used in published work:
56+
57+ - Space groups:
58+ [Aroyo et al., Z. Kristallogr. Cryst. Mater. **221**, 15
59+ (2006)](https://doi.org/10.1524/zkri.2006.221.1.15);
60+ - Point group: Bilbao Crystallographic Server's
61+ [2D and 3D GENPOS](https://www.cryst.ehu.es/cryst/get_point_genpos.html);
62+ - Subperiodic groups: Bilbao Crystallographic Server's
63+ [SUBPERIODIC GENPOS](https://www.cryst.ehu.es/subperiodic/get_sub_gen.html).
64+
65+ ## Extended help
66+
67+ Note that the returned generators are not guaranteed to be the smallest possible set of
68+ generators; i.e., there may exist other generators with fewer elements (an example is space
69+ group 168 (P6), for which the returned generators are `[2₀₀₁, 3₀₀₁⁺]` even though the group
70+ could be generated by just `[6₀₀₁⁺]`).
71+ The returned generators, additionally, are not guaranteed to be
72+ [minimal](https://en.wikipedia.org/wiki/Generating_set_of_a_module), i.e., they may include
73+ proper subsets that generate the group themselves (e.g., in space group 75 (P4), the
74+ returned generators are `[2₀₀₁, 4₀₀₁⁺]` although the subset `[4₀₀₁⁺]` is sufficient to
75+ generate the group).
76+ The motivation for this is to expose as similar generators as possible for similar crystal
77+ systems (see e.g. Section 8.3.5 of the International Tables of Crystallography, Vol. A,
78+ Ed. 5 (ITA) for further background).
79+
80+ Note also that, contrary to conventions in ITA, the identity operation is excluded among the
81+ returned generators (except in space group 1) since it composes trivially and adds no
82+ additional context.
83+ """
84+ function generators (sgnum:: Integer , :: Type{SpaceGroup{D}} = SpaceGroup{3 }) where D
85+ @boundscheck _check_valid_sgnum_and_dim (sgnum, D)
86+ codes = SG_GENS_CODES_Vs[D][sgnum]
87+
88+ # convert `codes` to `SymOperation`s and add to `operations`
89+ operations = Vector {SymOperation{D}} (undef, length (codes))
90+ _include_symops_from_codes! (operations, codes; add_identity= false )
91+
92+ return operations
93+ end
0 commit comments