spacegroup.jl

"""
    generators(num::Integer, T::Type{AbstractGroup{D}}[, optargs])
    generators(pgiuc::String, T::PointGroup{D}})              -->  Vector{SymOperation{D}}

Return the generators of the group type `T` which may be a `SpaceGroup{D}` or a 
`PointGroup{D}` parameterized by its dimensionality `D`. Depending on `T`, the group is
determined by inputting as the first argument:

- `SpaceGroup{D}`: the space group number `num::Integer`.
- `PointGroup{D}`: the point group IUC label `pgiuc::String` (see also
  [`pointgroup(::String)`) or the canonical point group number `num::Integer`, which can
  optionally be supplemented by an integer-valued setting choice `setting::Integer` (see
  also [`pointgroup(::Integer, ::Integer, ::Integer)`](@ref)]).
- `SubperiodicGroup{D}`: the subperiodic group number `num::Integer`.

Setting choices match those in [`spacegroup`](@ref), [`pointgroup`](@ref), and
[`subperiodicgroup`](@ref).

Iterated composition of the returned symmetry operations will generate all operations of the
associated space or point group (see [`generate`](@ref)).
As an example, `generate(generators(num, `SpaceGroup{D}))` and `spacegroup(num, D)` return
identical operations (with different sorting typically); and similarly so for point and
subperiodic groups.

## Example

Generators of space group 200:
```jldoctest
julia> generators(200, SpaceGroup{3})
4-element Vector{SymOperation{3}}:
 2₀₀₁
 2₀₁₀
 3₁₁₁⁺
 -1
```

Generators of point group m-3m:
```jldoctest
julia> generators("2/m", PointGroup{3})
2-element Vector{SymOperation{3}}:
 2₀₁₀
 -1
```

Generators of the Frieze group 𝓅2mg:
```jldoctest
julia> generators(7, SubperiodicGroup{2, 1})
2-element Vector{SymOperation{2}}:
 2
 {m₁₀|½,0}
```

## Citing

Please cite the original data sources if used in published work:

- Space groups:
  [Aroyo et al., Z. Kristallogr. Cryst. Mater. **221**, 15
  (2006)](https://doi.org/10.1524/zkri.2006.221.1.15);
- Point group: Bilbao Crystallographic Server's
  [2D and 3D GENPOS](https://www.cryst.ehu.es/cryst/get_point_genpos.html);
- Subperiodic groups: Bilbao Crystallographic Server's
  [SUBPERIODIC GENPOS](https://www.cryst.ehu.es/subperiodic/get_sub_gen.html).

## Extended help

Note that the returned generators are not guaranteed to be the smallest possible set of
generators; i.e., there may exist other generators with fewer elements (an example is space
group 168 (P6), for which the returned generators are `[2₀₀₁, 3₀₀₁⁺]` even though the group
could be generated by just `[6₀₀₁⁺]`).
The returned generators, additionally, are not guaranteed to be
[minimal](https://en.wikipedia.org/wiki/Generating_set_of_a_module), i.e., they may include
proper subsets that generate the group themselves (e.g., in space group 75 (P4), the
returned generators are `[2₀₀₁, 4₀₀₁⁺]` although the subset `[4₀₀₁⁺]` is sufficient to
generate the group).
The motivation for this is to expose as similar generators as possible for similar crystal
systems (see e.g. Section 8.3.5 of the International Tables of Crystallography, Vol. A,
Ed. 5 (ITA) for further background).

Note also that, contrary to conventions in ITA, the identity operation is excluded among the
returned generators (except in space group 1) since it composes trivially and adds no
additional context.
"""
function generators(sgnum::Integer, ::Type{SpaceGroup{D}}=SpaceGroup{3}) where D
    @boundscheck _check_valid_sgnum_and_dim(sgnum, D)
    codes = SG_GENS_CODES_Vs[D][sgnum]

    # convert `codes` to `SymOperation`s and add to `operations`
    operations = Vector{SymOperation{D}}(undef, length(codes))
    _include_symops_from_codes!(operations, codes; add_identity=false)

    return operations
end