API Reference¶

@dataclass
class CrystalDescription:
    """Complete crystal description parsed from CDL.

    The main output of CDL parsing, containing all information needed
    to generate a crystal visualization.

    Attributes:
        system: Crystal system ('cubic', 'hexagonal', etc.)
        point_group: Hermann-Mauguin point group symbol ('m3m', '6/mmm', etc.)
        forms: List of form nodes (CrystalForm or FormGroup)
        modifications: List of morphological modifications
        twin: Optional twin specification
        definitions: Optional list of named definitions

    Examples:
        >>> desc = parse_cdl("cubic[m3m]:{111}@1.0 + {100}@1.3")
        >>> desc.system
        'cubic'
        >>> len(desc.forms)
        2
    """

    system: str
    point_group: str
    forms: list[FormNode] = field(default_factory=list)
    modifications: list[Modification] = field(default_factory=list)
    twin: TwinSpec | None = None
    phenomenon: PhenomenonSpec | None = None
    doc_comments: list[str] | None = None
    definitions: list[Definition] | None = None

    def flat_forms(self) -> list[CrystalForm]:
        """Get a flat list of all CrystalForm objects (backwards compat).

        Recursively traverses FormGroup nodes to extract all CrystalForm leaves.
        Features from parent FormGroups are merged into child forms.
        """
        result: list[CrystalForm] = []
        for node in self.forms:
            result.extend(_flatten_node(node))
        return result

    def __str__(self) -> str:
        parts = [f"{self.system}[{self.point_group}]"]

        # Definitions
        if self.definitions:
            def_strs = [str(d) for d in self.definitions]
            parts = def_strs + parts

        # Forms (including features)
        form_strs = [str(f) for f in self.forms]
        parts.append(":" + " + ".join(form_strs))

        # Modifications
        if self.modifications:
            mod_strs = [str(m) for m in self.modifications]
            parts.append(" | " + ", ".join(mod_strs))

        # Twin
        if self.twin:
            parts.append(" | " + str(self.twin))

        # Phenomenon
        if self.phenomenon:
            parts.append(" | " + str(self.phenomenon))

        return "".join(parts)

    def to_dict(self) -> dict[str, Any]:
        """Convert to dictionary representation."""
        return {
            "system": self.system,
            "point_group": self.point_group,
            "forms": [_form_node_to_dict(f) for f in self.forms],
            "flat_forms": [
                {
                    "miller": f.miller.as_tuple(),
                    "scale": f.scale,
                    "name": f.name,
                    "label": f.label,
                    "features": [{"name": feat.name, "values": feat.values} for feat in f.features]
                    if f.features
                    else None,
                }
                for f in self.flat_forms()
            ],
            "modifications": [{"type": m.type, "params": m.params} for m in self.modifications],
            "twin": {
                "law": self.twin.law,
                "axis": self.twin.axis,
                "angle": self.twin.angle,
                "twin_type": self.twin.twin_type,
                "count": self.twin.count,
            }
            if self.twin
            else None,
            "phenomenon": {
                "type": self.phenomenon.type,
                "params": self.phenomenon.params,
            }
            if self.phenomenon
            else None,
            "doc_comments": self.doc_comments,
            "definitions": [
                {"name": d.name, "body": [_form_node_to_dict(f) for f in d.body]}
                for d in self.definitions
            ]
            if self.definitions
            else None,
        }

@dataclass
class MillerIndex:
    """Miller index representation.

    Represents crystal face orientations using Miller or Miller-Bravais notation.

    Attributes:
        h: First Miller index
        k: Second Miller index
        l: Third Miller index (fourth in Miller-Bravais)
        i: Third index for Miller-Bravais notation (hexagonal/trigonal)
           Calculated as -(h+k), only used for 4-index notation

    Examples:
        >>> MillerIndex(1, 1, 1)  # Octahedron face
        >>> MillerIndex(1, 0, 0)  # Cube face
        >>> MillerIndex(1, 0, 1, i=-1)  # Hexagonal {10-11}
    """

    h: int
    k: int
    l: int  # noqa: E741 - standard crystallographic notation
    i: int | None = None  # For Miller-Bravais (hexagonal/trigonal)

    def __post_init__(self) -> None:
        # Validate Miller-Bravais constraint: i = -(h+k)
        if self.i is not None:
            expected_i = -(self.h + self.k)
            if self.i != expected_i:
                raise ValueError(
                    f"Invalid Miller-Bravais index: i should be {expected_i}, got {self.i}"
                )

    def as_tuple(self) -> tuple[int, ...]:
        """Return as tuple (3 or 4 elements)."""
        if self.i is not None:
            return (self.h, self.k, self.i, self.l)
        return (self.h, self.k, self.l)

    def as_3index(self) -> tuple[int, int, int]:
        """Return as 3-index tuple (for calculations)."""
        return (self.h, self.k, self.l)

    def __str__(self) -> str:
        if self.i is not None:
            return f"{{{self.h}{self.k}{self.i}{self.l}}}"
        return f"{{{self.h}{self.k}{self.l}}}"

    def __repr__(self) -> str:
        if self.i is not None:
            return f"MillerIndex({self.h}, {self.k}, {self.l}, i={self.i})"
        return f"MillerIndex({self.h}, {self.k}, {self.l})"

@dataclass
class CrystalForm:
    """A crystal form with Miller index and scale.

    Represents a single crystal form (set of symmetry-equivalent faces)
    with an optional distance scale for truncation.

    Attributes:
        miller: The Miller index defining the form
        scale: Distance scale (default 1.0, larger = more truncated)
        name: Original name if using named form (e.g., 'octahedron')
        features: Optional list of feature annotations
        label: Optional label for the form (e.g., 'prism' in prism:{10-10})

    Examples:
        >>> CrystalForm(MillerIndex(1, 1, 1), scale=1.0)
        >>> CrystalForm(MillerIndex(1, 0, 0), scale=1.3, name='cube')
    """

    miller: MillerIndex
    scale: float = 1.0
    name: str | None = None  # Original name if using named form
    features: list[Feature] | None = None  # Per-form features [phantom:3]
    label: str | None = None  # Form label (v1.3)

    def __str__(self) -> str:
        s = str(self.miller)
        if self.name:
            s = f"{self.name}={s}"
        if self.label:
            s = f"{self.label}:{s}"
        if self.scale != 1.0:
            s += f"@{self.scale}"
        if self.features:
            feat_str = ", ".join(str(f) for f in self.features)
            s += f"[{feat_str}]"
        return s

class ParseError(CDLError):
    """Raised when CDL parsing fails.

    Attributes:
        message: Human-readable error description
        position: Character position in the input string where error occurred
        line: Optional line number (for multi-line inputs)
        column: Optional column number
    """

    def __init__(self, message: str, position: int = -1, line: int = -1, column: int = -1):
        self.message = message
        self.position = position
        self.line = line
        self.column = column
        super().__init__(self._format_message())

    def _format_message(self) -> str:
        parts = [self.message]
        if self.position >= 0:
            parts.append(f"at position {self.position}")
        if self.line >= 0:
            parts.append(f"(line {self.line}")
            if self.column >= 0:
                parts.append(f", column {self.column})")
            else:
                parts.append(")")
        return " ".join(parts)

class ValidationError(CDLError):
    """Raised when CDL validation fails.

    This is raised when the CDL syntax is correct but the content
    is semantically invalid (e.g., invalid point group for system).

    Attributes:
        message: Human-readable error description
        field: The field or component that failed validation
        value: The invalid value
    """

    def __init__(self, message: str, field: str = "", value: str = ""):
        self.message = message
        self.field = field
        self.value = value
        super().__init__(self._format_message())

    def _format_message(self) -> str:
        if self.field and self.value:
            return f"{self.message}: {self.field}='{self.value}'"
        elif self.field:
            return f"{self.message}: {self.field}"
        return self.message