API improvement to be ergonomic

[unkcpz]

when working with the crate, I find it would be easy to have some APIs that not expose too much computation logic but use some ergonomic rust like definition, I make a wrapper of moyo to be used by my crate and expect that can actually come from moyo crate as did in https://github.com/unkcpz/ccmat/blob/cb99c16edbd38c6288da4d6354fa75b4e30d6dc2/ccmat-symmetry/src/moyo_wrapper.rs

@lan496 Please let me know what you think and I'd happy to have a call to discuss it.

[lan496]

Thank you for your suggestions! I'll take a look that later

[lan496]

[Claude Code] Here is a summary of the proposed API improvements with implementation analysis:

Implementation Plan

✅1. Convenience methods on MoyoDataset (non-breaking, highest impact)

#272

Added hall_symbol() and arithmetic_crystal_class() methods to MoyoDataset. Downstream users can derive classification info (bravais_class, geometric_crystal_class, crystal_system, lattice_system, crystal_family) from ArithmeticCrystalClassEntry.

✅2. Error type re-export (non-breaking, small)

#265

MoyoError already implements std::error::Error and Display via thiserror. The only improvement needed is a convenience re-export:

// In moyo/src/lib.rs
pub use base::MoyoError as Error;

This lets users write moyo::Error instead of moyo::base::MoyoError.

✅3. Array accessor methods (non-breaking, additive)

#266

Add methods returning plain arrays so downstream users don't need nalgebra:

impl Lattice {
    /// Returns basis vectors as row vectors in a 3x3 array
    pub fn basis_as_array(&self) -> [[f64; 3]; 3];
}

impl Cell {
    /// Returns fractional positions as arrays
    pub fn positions_as_arrays(&self) -> Vec<[f64; 3]>;
}

impl Operation {
    /// Returns rotation matrix as a 3x3 array
    pub fn rotation_as_array(&self) -> [[i32; 3]; 3];
    /// Returns translation vector as an array
    pub fn translation_as_array(&self) -> [f64; 3];
}

Also added to NonCollinear, UnimodularTransformation, Transformation, MoyoDataset, and MoyoMagneticDataset.

Existing pub fields remain unchanged -- these are purely additive convenience methods.

4. Cell::new() validation (minor breaking change)

Currently Cell::new() panics on mismatched positions/numbers lengths. Change to return Result:

impl Cell {
    pub fn new(lattice: Lattice, positions: Vec<Position>, numbers: Vec<AtomicSpecie>)
        -> Result<Self, MoyoError>;
}

This requires a new MoyoError variant (e.g., MoyoError::InvalidCellError) and updating all call sites. This is the only breaking change in the set.

Deferred to next major version

• Type safety for numbers (item 4 in the issue): Newtype wrappers for Number, HallNumber, etc. -- breaking change, better bundled with a major release.
• Builder pattern for Cell (item 5): The Cell::new() -> Result change covers the main use case. A full type-state builder adds complexity without proportional benefit.
• Data module visibility (item 6): No change needed once convenience methods (item 1) exist.

Open questions for maintainers

1. Re-export nalgebra? Adding pub use nalgebra; in moyo/src/lib.rs would let downstream users access nalgebra types without version-matching. This is orthogonal to the array accessors.
2. Cell::new() breaking change: Should we make this change now, or keep the panic and add a separate Cell::try_new() -> Result instead?

[lan496]

[Claude Code] Plan 2 (Error type re-export) implemented in #265: added pub use base::MoyoError as Error; so users can write moyo::Error instead of moyo::base::MoyoError.

[lan496]

[Claude Code] Plan 1 (convenience methods on MoyoDataset) implemented in #272: added hall_symbol() and arithmetic_crystal_class() methods. Downstream users can derive bravais_class, geometric_crystal_class, crystal_system, lattice_system, and crystal_family from ArithmeticCrystalClassEntry.