Spglib

Documentation for Spglib.

See the Index for the complete list of documented functions and types.

The code, which is hosted on GitHub, is tested using various continuous integration services for its validity.

This repository is created and maintained by @singularitti, and contributions are highly welcome.

Package features

• It enables the finding and handling of crystal symmetries.
• The design of the package includes new naming conventions, input types, and return types of functions.

Installation

The package can be installed with the Julia package manager. From the Julia REPL, type ] to enter the Pkg mode and run:

pkg> add Spglib

Or, equivalently, via Pkg.jl:

julia> import Pkg; Pkg.add("Spglib")   Resolving package versions...
   Installed SumTypes ─── v0.5.5
   Installed MacroTools ─ v0.5.13
   Installed Spglib ───── v0.9.3
    Updating `~/work/Spglib.jl/Spglib.jl/docs/Project.toml`
  [f761d5c5] ~ Spglib v0.9.4 `~/.julia/dev/Spglib` ⇒ v0.9.3
    Updating `~/work/Spglib.jl/Spglib.jl/docs/Manifest.toml`
  [1914dd2f] + MacroTools v0.5.13
  [f761d5c5] ~ Spglib v0.9.4 `~/.julia/dev/Spglib` ⇒ v0.9.3
  [8e1ec7a9] + SumTypes v0.5.5
Precompiling project...
  ✓ MacroTools
  ✓ SumTypes
  ✓ Spglib
  3 dependencies successfully precompiled in 4 seconds. 29 already precompiled.
  1 dependency precompiled but a different version is currently loaded. Restart julia to access the new version

Documentation

• STABLE — documentation of the most recently tagged version.
• DEV — documentation of the in-development version.

Project status

The package is developed for and tested against Julia v1.6 and above on Linux, macOS, and Windows.

Questions and contributions

You can post usage questions on our discussion page.

We welcome contributions, feature requests, and suggestions. If you encounter any problems, please open an issue. The Contributing page has a few guidelines that should be followed when opening pull requests and contributing code.

Manual outline

• Installation Guide
• • Install Julia
  • • Which version should I pick?
  • Install the package
  • Update the package
  • Uninstall and then reinstall the package
• Definitions and conventions
• • Basis vectors
  • Atomic point coordinates
  • Space group operation and change of basis
  • • Symmetry operation $(\mathbf{W}, \mathbf{w})$
    • Transformation matrix $\mathbf{P}$ and origin shift $\mathbf{p}$
    • Difference between rotation and transformation matrices
  • Spglib conventions of standardized unit cell
  • • Transformation to the primitive cell
    • Idealization of unit cell structure
    • Rotation introduced by idealization
• Spglib dataset
• • Space group type
  • • spacegroup_number
    • hall_number
    • international_symbol
    • hall_symbol
    • choice
  • Symmetry operations
  • • rotations, translations, and n_operations
  • Wyckoff positions and symmetrically equivalent atoms
  • • n_atoms
    • wyckoffs
    • site_symmetry_symbols
    • equivalent_atoms
    • crystallographic_orbits
  • Transformation matrix and origin shift
  • • transformation_matrix and origin_shift
  • Standardized crystal structure after idealization
  • • n_std_atoms, std_lattice, std_types, and std_positions
    • std_rotation_matrix
    • std_mapping_to_primitive
  • Crystallographic point group
  • • pointgroup_symbol
  • Intermediate data in symmetry search
  • • primitive_lattice
    • mapping_to_primitive
• Magnetic dataset (experimental)
• • Magnetic space-group type
  • • uni_number
    • msg_type
    • hall_number
    • tensor_rank
  • Magnetic symmetry operations
  • • n_operations
    • rotations
    • translations
    • time_reversals
  • Symmetrically equivalent atoms
  • • n_atoms and equivalent_atoms
  • Transformation to standardized setting
  • • transformation_matrix and origin_shift
  • Standardized magnetic crystal structure after idealization
  • • n_std_atoms, std_lattice, std_types, std_positions, and std_rotation_matrix
    • std_tensors
  • Intermediate data in symmetry search
  • • primitive_lattice
• Examples
• • Creating a Cell
  • Crystallographic choice and rigid rotation
  • Transformation to a primitive cell
  • Computing rigid rotation introduced by idealization
• Troubleshooting
• • Cannot find the Julia executable
  • Julia starts slow
  • Unable to install the package
  • Returned cell symmetry is wrong
  • Julia's results are different from Python's
• Contributing
• • Code of conduct
  • Join the community forum
  • Improve the documentation
  • File a bug report
  • Contribute code to Spglib
  • • Step 1: decide what to work on
    • Step 2: fork Spglib
    • Step 3: install Spglib locally
    • Step 4: checkout a new branch
    • Step 5: make changes
    • Step 6a: test your code changes
    • Step 6b: test your documentation changes
    • Step 7: make a pull request
    • Step 8: respond to comments
    • Step 9: cleaning up
• Style Guide
• • Formatting
  • • Run JuliaFormatter
    • Use the Julia extension for Visual Studio Code
• Design Principles
• • Consistency vs adherence
  • Community contribution guidelines
  • Open source contributions are allowed to start small and grow over time
  • Generic code is preferred unless code is known to be specific
  • Internal types should match the types used by users when possible
  • Trait definition and adherence to generic interface is preferred when possible
  • Macros should be limited and only be used for syntactic sugar
  • Errors should be caught as early as possible, and error messages should be made contextually clear for newcomers
  • Subpackaging and interface packages is preferred over conditional modules via Requires.jl
  • Functions should either attempt to be non-allocating and reuse caches, or treat inputs as immutable
  • Out-of-place and immutability is preferred when sufficient performant
  • Tests should attempt to cover a wide gamut of input types
  • When in doubt, a submodule should become a subpackage or separate package
  • Globals should be avoided whenever possible
  • Type-stable and type-grounded code is preferred wherever possible
  • Closures should be avoided whenever possible
  • Numerical functionality should use the appropriate generic numerical interfaces
  • Functions should capture one underlying principle
  • Internal choices should be exposed as options whenever possible
  • Prefer code reuse over rewrites whenever possible
  • Prefer to not shadow functions

Library outline

• Public API
• • Contents
  • Index
  • Public interface
• Error
• Brillouin zone meshes

Index

• CrystallographyCore.Lattice
• Spglib.Dataset
• Spglib.MagneticDataset
• Spglib.MagneticSpacegroupType
• Spglib.SpacegroupType
• Spglib.SpglibCell
• CrystallographyCore.atomtypes
• CrystallographyCore.natoms
• Spglib.delaunay_reduce
• Spglib.eachpoint
• Spglib.find_primitive
• Spglib.get_dataset
• Spglib.get_dataset_with_hall_number
• Spglib.get_error_code
• Spglib.get_error_message
• Spglib.get_hall_number_from_symmetry
• Spglib.get_international
• Spglib.get_ir_reciprocal_mesh
• Spglib.get_magnetic_dataset
• Spglib.get_magnetic_spacegroup_type
• Spglib.get_magnetic_spacegroup_type_from_symmetry
• Spglib.get_magnetic_symmetry_from_database
• Spglib.get_multiplicity
• Spglib.get_schoenflies
• Spglib.get_spacegroup_type
• Spglib.get_spacegroup_type_from_symmetry
• Spglib.get_stabilized_reciprocal_mesh
• Spglib.get_symmetry
• Spglib.get_symmetry_from_database
• Spglib.get_symmetry_with_collinear_spin
• Spglib.get_symmetry_with_site_tensors
• Spglib.get_version
• Spglib.niggli_reduce
• Spglib.refine_cell
• Spglib.standardize_cell