Dev

[bjmorgan]

This pull request introduces significant performance improvements, adds new composition enumeration capabilities, and modernises the codebase, development workflow, and documentation for the bsym project. The most important changes include rewritten documentation, substantial speedups through vectorised operations and optimised data structures, a new feature for systematic exploration of composition ranges, updated Python version requirements, and enhanced development infrastructure.

Documentation and usability improvements:

• Completely restructured documentation with new hierarchy separating theoretical concepts from practical usage:
  • Getting Started: introduction, installation, and quickstart guide
  • User Guide: practical examples as executable Jupyter notebooks (basic substitutions, fixed composition substitutions, varying composition enumeration)
  • Theory and Core Concepts: detailed mathematical explanations as Markdown documents (configuration spaces, symmetry operations, unique configuration enumeration, composition enumeration)
  • API Reference: auto-generated class and method documentation
• Converted narrative documentation from reStructuredText to Markdown where appropriate for better readability and maintainability.
• Created comprehensive theory documents explaining the mathematical foundations of configuration spaces, symmetry operations, and enumeration algorithms.
• Added practical Jupyter notebook tutorials demonstrating real-world usage with pymatgen structures.
• Added documentation examples demonstrating multi-level disorder enumeration capabilities.
• Expanded and clarified the README.md with sections on requirements, installation (including development setup), testing, and example usage.
• Updated .readthedocs.yaml to use the new Python version and modern dependency specification for building documentation.

Performance optimisations:

• Implemented batched symmetry operations using cached stacked_index_mappings and unique_index_mappings properties, replacing individual loops with vectorised NumPy operations.
• Optimised Configuration storage to use np.int8 arrays, achieving optimal balance of speed and memory efficiency with consistent byte-level representations throughout the codebase.
• Substantially improved configuration enumeration performance through vectorised operations and optimised data types. For example, a 2×2×2 supercell of TiOF₂ with 735,471 permutations shows a 4.7× speedup (35.6s → 7.6s).

Varying composition enumeration feature:

• Added unique_configurations_by_composition method to ConfigurationSpace class, enabling systematic exploration of composition ranges (e.g., A₄, A₃B, A₂B₂, AB₃, B₄ for binary systems).
• Implemented species exchange symmetry optimisation that analyses only canonical compositions and generates equivalent compositions through relabelling, reducing expensive symmetry analyses.
• Implemented supporting utilities: generate_partitions for integer partitioning, compute_mapping_vectors for species permutation mapping, and satisfies_bounds for occupancy constraint validation.

Python version and dependency updates:

• Updated the minimum required Python version to 3.10 across the codebase, documentation, and CI, and added support for Python 3.13 and 3.14 in the test matrix.
• Updated installation instructions in README.md to reflect the new Python version requirement and modern installation practices.

Development workflow and CI enhancements:

• Modernised the GitHub Actions workflow: improved dependency installation, enabled pip caching, parallelised coverage reporting, and updated Coveralls integration.
• Migrated CI pipeline to use pytest as test runner whilst maintaining unittest-based test suite.
• Added mypy static type checking to CI pipeline with comprehensive type annotations across the codebase.
• Removed the obsolete .coveragerc file.

Type annotations and code modernisation:

• Added comprehensive type annotations throughout the codebase including configuration_space.py, permutations.py, colour_operation.py, and related modules for better static analysis and code readability.
• Used modern Python syntax and type hints compatible with Python 3.10+.