Updated docs

Author: bjmorgan

docs/source/development.rst

@@ -0,0 +1,36 @@
+# Installation
+
+## Requirements
+
+bsym requires Python 3.10 or later.
+
+## Standard Installation
+
+Install from PyPI:
+```bash
+pip install bsym
+```
+
+## Installation from Source
+
+Clone the repository and install:
+```bash
+git clone https://github.com/bjmorgan/bsym.git
+cd bsym
+pip install .
+```
+
+## Development Installation
+
+For development work (running tests, building documentation):
+```bash
+git clone https://github.com/bjmorgan/bsym.git
+cd bsym
+pip install -e ".[dev]"
+```
+
+## Verifying Installation
+```python
+import bsym
+print(bsym.__version__)
+```

docs/source/getting_started/installation.md

@@ -0,0 +1,114 @@
+# Introduction to bsym
+
+## What is bsym?
+
+bsym is a Python package for working with symmetry operations and enumerating symmetry-inequivalent configurations. It provides tools for:
+
+- Defining abstract configuration spaces and their symmetry operations
+- Finding all unique arrangements of objects that respect symmetry constraints
+- Generating symmetry-inequivalent crystal structures with substitutional disorder
+
+## What Problems Does bsym Solve?
+
+### The Configuration Counting Problem
+
+Consider a crystal with 16 anion sites where you want to substitute 8 oxygen atoms for 8 fluorine atoms. Without considering symmetry, there are $\binom{16}{8} = 12,870$ possible arrangements. However, if the crystal has symmetry operations (rotations, reflections, translations), many of these arrangements are equivalent - they're just the same structure viewed from different angles or shifted in space.
+
+bsym identifies which arrangements are truly unique, dramatically reducing the number of structures you need to consider. For example, a high-symmetry crystal might have only a few dozen unique arrangements instead of thousands.
+
+### Why This Matters
+
+**For computational materials science:**
+- Generate training sets for machine learning with only symmetry-inequivalent structures
+- Calculate configuration-dependent properties efficiently
+- Build phase diagrams by exploring composition space systematically
+- Study defects and disorder without redundant calculations
+
+**For mathematical and theoretical work:**
+- Explore combinatorial problems with symmetry constraints
+- Study group theory applications
+- Develop enumeration algorithms
+
+**For general research:**
+- Avoid wasting computational resources on equivalent configurations
+- Ensure systematic coverage of configuration space
+- Calculate degeneracies for statistical mechanics
+
+## Key Features
+
+### Abstract Configuration Spaces
+
+Work with symmetry at a mathematical level, independent of any physical system:
+```python
+from bsym import ConfigurationSpace, SymmetryGroup
+
+config_space = ConfigurationSpace(objects=[1, 2, 3, 4])
+unique_configs = config_space.unique_configurations({1: 2, 0: 2})
+```
+
+### Crystallographic Interface
+
+Integration with pymatgen for crystal structure generation:
+```python
+from bsym.interface.pymatgen import unique_structure_substitutions
+
+unique_structures = unique_structure_substitutions(
+    parent_structure, 'F', {'O': 8, 'F': 8}
+)
+```
+
+### Efficient Algorithms
+
+- Smart enumeration that only performs symmetry analysis when needed
+- Species exchange optimization for composition enumeration
+- Progress tracking for large systems
+
+### Degeneracy Tracking
+
+Each unique configuration includes its degeneracy - the number of symmetry-equivalent arrangements it represents. This is essential for statistical mechanics calculations.
+
+## Who is bsym For?
+
+**Computational materials scientists** studying:
+- Solid solutions and substitutional disorder
+- Defect configurations
+- Surface adsorption patterns
+- Magnetic ordering
+
+**Researchers in related fields** working on:
+- Combinatorial problems with symmetry
+- Group theory applications
+- Enumeration algorithms
+
+**Students** learning about:
+- Crystallographic symmetry
+- Group theory
+- Configuration spaces
+
+## The Approach
+
+bsym separates the mathematical logic of symmetry from the physical details of specific systems:
+
+1. **Abstract representation**: Configurations are vectors of integers, symmetry operations are permutations
+2. **Efficient computation**: Symmetry operations implemented as numpy array indexing, with hash-based configuration lookup
+3. **Physical interpretation**: Map results back to structures, coordinates, etc. when needed
+
+This separation makes the algorithms system-agnostic and computationally efficient.
+
+## What's Next?
+
+- **[Installation](installation.md)**: Get bsym installed
+- **[Quickstart](quickstart.md)**: Try hands-on examples
+- **[User Guide](../user_guide/index.rst)**: Detailed tutorials for specific tasks
+- **[Theory](../theory/index.rst)**: Understand the concepts and algorithms
+
+## Further Reading
+
+For the theoretical background and detailed algorithm descriptions:
+- [Configuration Spaces](../theory/configuration_spaces.md)
+- [Symmetry Operations](../theory/symmetry_operations.md)
+- [Unique Configuration Enumeration](../theory/unique_configurations.md)
+
+For practical applications:
+- [Basic Substitutions](../user_guide/basic_substitutions.ipynb)
+- [Varying Composition](../user_guide/varying_composition.ipynb)

docs/source/getting_started/introduction.md

@@ -0,0 +1,164 @@
+# Quickstart Guide
+
+This guide provides quick examples to get you started with bsym, covering both abstract configuration spaces and practical crystallographic applications.
+
+## Abstract Example: Symmetry-Inequivalent Arrangements
+
+This example shows how to find unique arrangements of objects in a symmetric space without requiring any crystallographic knowledge.
+
+### Problem: Four Sites in a Square
+
+Consider four sites arranged in a square. How many unique ways can we place 2 occupied and 2 vacant sites, accounting for the square's rotational and reflection symmetry?
+
+![Square configuration space](../theory/figures/square_configuration_space.pdf)
+
+### Solution
+```python
+from bsym import ConfigurationSpace, SymmetryGroup, SymmetryOperation
+
+# Define C4v symmetry operations (square symmetry)
+e = SymmetryOperation.from_vector([1, 2, 3, 4], label='E')
+c4 = SymmetryOperation.from_vector([2, 3, 4, 1], label='C4')
+c4_inv = SymmetryOperation.from_vector([4, 1, 2, 3], label='C4i')
+c2 = SymmetryOperation.from_vector([3, 4, 1, 2], label='C2')
+sigma_x = SymmetryOperation.from_vector([4, 3, 2, 1], label='s_x')
+sigma_y = SymmetryOperation.from_vector([2, 1, 4, 3], label='s_y')
+sigma_ac = SymmetryOperation.from_vector([1, 4, 3, 2], label='s_ac')
+sigma_bd = SymmetryOperation.from_vector([3, 2, 1, 4], label='s_bd')
+
+# Create symmetry group
+c4v = SymmetryGroup([e, c4, c4_inv, c2, sigma_x, sigma_y, sigma_ac, sigma_bd])
+
+# Create configuration space
+config_space = ConfigurationSpace(
+    objects=['a', 'b', 'c', 'd'],
+    symmetry_group=c4v
+)
+
+# Find unique configurations (2 occupied, 2 vacant)
+unique_configs = config_space.unique_configurations({1: 2, 0: 2})
+
+print(f"Found {len(unique_configs)} unique configurations")
+for config in unique_configs:
+    print(f"{config.tolist()}: degeneracy = {config.count}")
+```
+
+**Output:**
+```
+Found 2 unique configurations
+[0, 0, 1, 1]: degeneracy = 4
+[0, 1, 0, 1]: degeneracy = 2
+```
+
+Without symmetry, there would be 6 distinct arrangements. With C<sub>4v</sub> symmetry, these reduce to just 2 unique patterns:
+- Adjacent sites occupied (4 equivalent arrangements)
+- Diagonal sites occupied (2 equivalent arrangements)
+
+### Next Steps
+
+- Learn about [configuration spaces](../theory/configuration_spaces.md)
+- Understand [symmetry operations](../theory/symmetry_operations.md)
+- Read about the [enumeration algorithm](../theory/unique_configurations.md)
+
+## Crystallographic Example: Disordered Structures
+
+This example shows how to generate symmetry-inequivalent crystal structures with substitutional disorder.
+
+### Problem: O/F Disorder in a Fluorite Structure
+
+Generate all unique structures for a 2×2×1 CaF<sub>2</sub> supercell where we substitute 8 oxygen atoms for 8 of the 16 fluorine atoms.
+
+### Solution
+```python
+from pymatgen.core import Structure
+from bsym.interface.pymatgen import unique_structure_substitutions
+
+# Load parent structure (CaF2 2x2x1 supercell)
+parent_structure = Structure.from_file('CaF2_supercell.cif')
+# Or create programmatically using pymatgen
+
+# Generate all unique O/F arrangements
+unique_structures = unique_structure_substitutions(
+    structure=parent_structure,
+    to_substitute='F',           # Substitute on F sites
+    site_distribution={'O': 8, 'F': 8}  # 8 O, 8 F
+)
+
+print(f"Found {len(unique_structures)} symmetry-inequivalent structures")
+
+# Check degeneracies
+for i, structure in enumerate(unique_structures[:3]):
+    n_equiv = structure.number_of_equivalent_configurations
+    print(f"Structure {i}: represents {n_equiv} equivalent configurations")
+
+# Export structures
+for i, structure in enumerate(unique_structures):
+    structure.to(filename=f'CaF2_O8F8_{i}.cif', fmt='cif')
+```
+
+**Output:**
+```
+Found 47 symmetry-inequivalent structures
+Structure 0: represents 192 equivalent configurations
+Structure 1: represents 192 equivalent configurations
+Structure 2: represents 96 equivalent configurations
+```
+
+The `unique_structure_substitutions` function:
+1. Automatically detects the space group symmetry
+2. Identifies all symmetry-equivalent F sites
+3. Enumerates only the symmetry-inequivalent O/F arrangements
+4. Returns pymatgen `Structure` objects with degeneracy information
+
+### Exploring Multiple Compositions
+
+To generate structures across different O:F ratios:
+```python
+from bsym.interface.pymatgen import unique_structure_substitutions_by_composition
+
+# Generate structures for all O:F compositions
+all_structures = unique_structure_substitutions_by_composition(
+    structure=parent_structure,
+    to_substitute='F',
+    species=['O', 'F']
+)
+
+# Results organized by composition
+for composition, structures in all_structures.items():
+    n_O, n_F = composition
+    print(f"CaO{n_O}F{n_F}: {len(structures)} unique structures")
+```
+
+### Next Steps
+
+- See [Basic Substitutions](../user_guide/basic_substitutions.ipynb) for more examples
+- Learn about [varying composition](../user_guide/varying_composition.ipynb)
+- Understand [degeneracy tracking](../user_guide/fixed_composition.ipynb)
+
+## Key Concepts
+
+### Configuration Space
+An abstract vector space where you arrange different types of objects across discrete positions.
+
+### Symmetry Operations
+Transformations that map the configuration space onto itself (rotations, reflections, etc.).
+
+### Symmetry-Inequivalent Configurations
+The minimal set of configurations where no two can be transformed into each other by symmetry operations.
+
+### Degeneracy
+The number of symmetry-equivalent configurations represented by each unique configuration.
+
+## Where to Go Next
+
+**For abstract/mathematical applications:**
+- [Theory: Configuration Spaces](../theory/configuration_spaces.md)
+- [Theory: Symmetry Operations](../theory/symmetry_operations.md)
+
+**For crystallographic applications:**
+- [User Guide: Basic Substitutions](../user_guide/basic_substitutions.ipynb)
+- [User Guide: Varying Composition](../user_guide/varying_composition.ipynb)
+
+**For understanding the algorithms:**
+- [Theory: Unique Configuration Enumeration](../theory/unique_configurations.md)
+- [Theory: Composition Enumeration](../theory/composition_enumeration.md)

docs/source/getting_started/quickstart.md

@@ -10,10 +10,9 @@ bsym - A basic symmetry module
    :caption: Contents:
 
    getting_started/index
-   theory/index
    user_guide/index
+   theory/index
    api/modules
-   examples/bsym_examples
 
 Indices and tables
 ==================