types — CalabiYauLite, ExtremalContraction, and ContractionType

types — CalabiYauLite, ExtremalContraction, and ContractionType#

Core data types for cybir.

Provides CalabiYauLite, ExtremalContraction, ContractionType, CoxeterGroup, and InsufficientGVError.

class CalabiYauLite(int_nums, c2=None, kahler_cone=None, mori_cone=None, polytope=None, charges=None, indices=None, eff_cone=None, triangulation=None, fan=None, gv_invariants=None, label=None, curve_signs=None, tip=None)#

Bases: object

Lightweight container for Calabi-Yau phase data.

Stores precomputed intersection numbers, second Chern class, cones, and charge matrices. Interface-compatible with the dbrane-tools CalabiYauLite class, with additional fields for GV invariants and a phase label.

Mutable during construction; call freeze() to make immutable after the EKC orchestrator finishes building.

Parameters:

  • int_nums (numpy.ndarray) – Triple intersection numbers \(\kappa_{ijk}\).

  • c2 (numpy.ndarray, optional) – Second Chern class \(c_2 \cdot D_i\).

  • kahler_cone (optional) – Kahler cone (cytools.Cone).

  • mori_cone (optional) – Mori cone (cytools.Cone).

  • polytope (optional) – The underlying polytope.

  • charges (optional) – CY charge matrix.

  • indices (optional) – CY labels list.

  • eff_cone (optional) – Effective cone (cytools.Cone).

  • triangulation (optional) – A cytools.triangulation.Triangulation.

  • fan (optional) – A cytools.vector_config.fan.Fan.

  • gv_invariants (optional) – Reference to a CYTools Invariants object.

  • label (optional) – Phase identifier for the adjacency graph.

property c2#

Second Chern class \(c_2 \cdot D_i\).

property charges#

CY charge matrix.

property curve_signs#

+1/-1}.

Records the sign of tip @ curve for each known flop curve. Persisted during BFS construction for use in orbit expansion and on-demand GV reconstruction (D-15).

Type:

Curve-sign dictionary {curve_tuple

property eff_cone#

Effective cone (cytools.Cone).

property fan#

A cytools.vector_config.fan.Fan.

flop(curve, gv_series, label=None)#

Create a new phase by flopping across a wall.

Thin wrapper around cybir.core.flop.flop_phase().

Parameters:

  • curve (numpy.ndarray) – Flopping curve class.

  • gv_series (list[int]) – GV series for the flopping curve.

  • label (str, optional) – Label for the new phase.

Returns:

CalabiYauLite – New phase with transformed intersection numbers and c2.

freeze()#

Make this object immutable.

Called by the EKC orchestrator after construction is complete. After freezing, any attempt to set an attribute raises AttributeError.

property gv_invariants#

Reference to a CYTools Invariants object.

property indices#

CY labels list.

property int_nums#

Triple intersection numbers \(\kappa_{ijk}\).

property kahler_cone#

Kahler cone (cytools.Cone).

property label#

Phase identifier for the adjacency graph.

property mori_cone#

Mori cone (cytools.Cone).

property polytope#

The underlying polytope.

property tip#

Interior point of the Kahler cone.

Persisted during BFS construction for use in orbit expansion and curve-sign computation (D-15).

property triangulation#

A cytools.triangulation.Triangulation.

class ContractionType(*values)#

Bases: Enum

Type of extremal birational contraction.

Eight types following the classification in arXiv:2212.10573: asymptotic, CFT, su(2) enhancement, su(2) enhancement at non-generic complex structure, symmetric flop, gross flop, generic flop, plus an UNRESOLVED sentinel for walls that require higher GV degree than the ceiling allows.

display_name(notation='paper')#

Return human-readable name in the given notation.

Parameters:

notation (str) – Either "paper" (default) for arXiv notation or "wilson" for Wilson’s Type I/II/III convention.

Returns:

str

class CoxeterGroup(factors, order_matrix, reflections)#

Bases: object

Coxeter group data from orbit expansion.

Parameters:

  • factors (tuple) – Tuple of (family, rank, order) tuples, one per irreducible component.

  • order_matrix (object) – The Coxeter order matrix m_ij (numpy.ndarray).

  • reflections (tuple) – The generator reflection matrices as a tuple of numpy arrays.

property order#

Total group order \(|W|\) (product of factor orders).

property rank#

Total rank (sum of factor ranks).

class ExtremalContraction(contraction_curve, contraction_type=None, gv_invariant=None, effective_gv=None, zero_vol_divisor=None, coxeter_reflection=None, gv_series=None, gv_eff_1=None, cone_face=None, toric_origin=None)#

Bases: object

An extremal birational contraction between two CY3 phases.

Represents a wall in the extended Kahler cone where a curve shrinks to zero volume. Frozen by default after construction.

Parameters:

  • contraction_curve (numpy.ndarray) – The curve class that shrinks at this wall.

  • contraction_type (ContractionType, optional) – Classification of this contraction.

  • gv_invariant (int, optional) – Gopakumar-Vafa invariant for the flopping curve.

  • effective_gv (int, optional) – Effective GV invariant (accounting for multiplicity).

  • zero_vol_divisor (numpy.ndarray, optional) – Divisor that shrinks at this wall.

  • coxeter_reflection (numpy.ndarray, optional) – Coxeter reflection matrix for this contraction.

  • gv_series (list of int, optional) – GV series \([n^0_{[\mathcal{C}]}, n^0_{2[\mathcal{C}]}, \ldots]\).

  • gv_eff_1 (int, optional) – Linear effective GV invariant \(\sum_k k \, n^0_{k[\mathcal{C}]}\).

  • cone_face (optional) – Reference to the Mori cone face associated with this contraction.

  • toric_origin (str, optional) – Toric origin tag (e.g. "flop") when this contraction was identified from toric data.

property cone_face#

Mori cone face associated with this contraction.

property contraction_curve#

The curve class that shrinks at this wall.

property contraction_type#

Classification of this contraction.

property coxeter_reflection#

Coxeter reflection matrix for this contraction.

property effective_gv#

Effective GV invariant (accounting for multiplicity).

property gv_eff_1#

Linear effective GV invariant \(\sum_k k \, n^0_{k[\mathcal{C}]}\).

property gv_invariant#

Gopakumar-Vafa invariant for the flopping curve.

property gv_series#

GV series \([n^0_{[\mathcal{C}]}, n^0_{2[\mathcal{C}]}, \ldots]\).

property toric_origin#

Toric origin tag for this contraction, if any.

property zero_vol_divisor#

Divisor that shrinks at this wall.

exception InsufficientGVError#

Bases: RuntimeError

Raised when GV series has not been computed to high enough degree.

class PartialClassification(zero_vol_divisor, coxeter_reflection, is_asymptotic, is_cft, determined, remaining_options, needs_for_disambiguation)#

Bases: object

Geometric-only classification of an extremal contraction curve.

Returned by cybir.diagnose_curve() when called with compute_gvs=False and no GV series provided. Captures everything determinable from triple intersection numbers, the second Chern class, and the curve class alone – no GV invariants required.

The geometric checks (asymptotic, CFT, zero-volume divisor existence, Coxeter-reflection integrality) are sufficient to fully classify the contraction in some cases. When they are not, determined is None and remaining_options lists which contraction types remain possible after geometric narrowing; computing GVs is required to disambiguate among them.

Parameters:

  • zero_vol_divisor (object) – Integer divisor with \(D \cdot \mathcal{C} < 0\), or None if no zero-volume divisor exists or the null space is higher-dimensional. See cybir.core.classify.zero_vol_divisor().

  • coxeter_reflection (object) – Coxeter reflection matrix on the lattice when a zero-volume divisor exists; None otherwise.

  • is_asymptotic (bool) – True if the projected triple intersection numbers vanish.

  • is_cft (bool) – True if the projected intersection-number matrix is rank-deficient.

  • determined (object) – Set when geometry alone pins the type down (ASYMPTOTIC, CFT, or FLOP from no-zvd / non-integer-reflection paths). None when GVs are needed to disambiguate.

  • remaining_options (tuple) – Contraction types still possible. Length 1 when determined is set; longer when GVs are needed.

  • needs_for_disambiguation (str) – Short prose explanation of what GV data would resolve the remaining options. Empty string when determined is set.

Examples

>>> from cybir import diagnose_curve
>>> partial = diagnose_curve(cy, [1, 0, -1], compute_gvs=False)
>>> if partial.determined is not None:
...     print(f"Classified as {partial.determined.name} from geometry alone")
... else:
...     print(f"GVs needed; possibilities: {partial.remaining_options}")