ekc — Birational class orchestrator and result API

ekc — Birational class orchestrator and result API#

CYBirationalClass orchestrator for extended Kahler cone construction.

The main result container and query API for GV-based EKC computation. Construction is performed by builder modules (build_gv, weyl); this class owns the result data and provides read-only access.

See arXiv:2212.10573 and arXiv:2303.00757 for the underlying theory.

class CYBirationalClass(cy, gvs=None)#

Bases: object

Orchestrator and result container for EKC construction.

Holds a CYGraph of phases and contractions, a reference to the root CYTools CalabiYau, cone generators accumulated during BFS, and Weyl expansion data.

Parameters:

cy (cytools.calabiyau.CalabiYau) – The root Calabi-Yau threefold.
gvs (cytools.calabiyau.Invariants, optional) – Pre-computed GV invariants. If provided, setup_root skips the expensive compute_gvs call. Useful for caching GVs across multiple runs on the same geometry.

Notes

Construction follows a step-by-step API (arXiv:2303.00757):

ekc = CYBirationalClass(cy) – cheap: wraps CY, creates empty graph
ekc.setup_root(max_deg=10) – moderate: computes GVs
ekc.construct_phases(verbose=True) – expensive: BFS
ekc.apply_coxeter_orbit() – optional: Coxeter orbit expansion

Or use the convenience classmethod CYBirationalClass.from_gv(cy).

Examples

>>> ekc = CYBirationalClass.from_gv(cy, max_deg=10)
>>> ekc.phases
[CalabiYauLite(label='CY_0'), ...]
>>> ekc.coxeter_matrix
array([[...]])

apply_coxeter_orbit(reflections='ekc', phases=True)#

Expand to the extended/hyperextended cone via Coxeter group orbit.

Parameters:

reflections (str or iterable, optional) –
Which reflections to use for orbit expansion:
- 'ekc' (default): symmetric flop reflections only (produces EKC)
- 'hekc': sym flop + SU2_NONGENERIC_CS (produces HEKC)
- 'all': all Coxeter reflections (full group)
- Custom iterable of reflection matrices
phases (bool, optional) – If True (default), create full reflected phase objects. If False, only accumulate cone generators.

See also

arXiv: 2212.10573 Section 4.3

toric_curves(phase_label=None)#

Access toric curve data, optionally re-oriented for a phase.

Parameters:: phase_label (str, optional) – If provided, re-orient curves for this phase’s Kahler cone. If None, return curves in canonical orientation.
Returns:: ToricCurveData or None

vex_phases()#

Labels of all vex phases.

Returns:: list of str

diagnose_curve(cy, curve, max_deg=10, gvs=None, ekc=None, *, compute_gvs=True)#

Classify an extremal contraction curve with minimal setup.

Convenience function that handles grading vector computation and GV series extraction internally. When an ekc (CYBirationalClass) with toric data is provided, also cross-checks against toric classification and combinatorial GV invariants (per D-12).

With compute_gvs=False and no gvs provided, performs only geometric checks (asymptotic, CFT, zero-volume divisor existence, Coxeter-reflection integrality) and returns a PartialClassification. Use this when the GV computation is too expensive and you want to know whether geometry alone suffices, or which contraction types are still possible.

Parameters:

cy (cytools.CalabiYau) – The Calabi-Yau threefold.
curve (array_like) – Curve class in the h11 basis.
max_deg (int, optional) – Maximum degree for GV computation. Default 10. Ignored when compute_gvs=False and gvs is None.
gvs (Invariants or list, optional) – Pre-computed GV invariants. Accepts either a CYTools Invariants object or a plain list [GV(C), GV(2C), GV(3C), ...]. When provided, the compute_gvs flag is ignored.
ekc (CYBirationalClass, optional) – If provided and ekc._toric_curve_data is available, adds toric_type and toric_gv keys to the result dict when the curve matches a toric curve. Has no effect on the lazy / geometric path.
compute_gvs (bool, default True) – If False AND gvs is None, skip the (potentially expensive) GV computation step and return a PartialClassification instead of the full classification dict. If gvs is provided, this flag is ignored and full classification proceeds.

Returns:

dict or PartialClassification – When compute_gvs=True (default) or gvs is provided, returns the full classification dict from classify_contraction: contraction_type, zero_vol_divisor, coxeter_reflection, gv_invariant, effective_gv, gv_eff_1, gv_series. When ekc is provided and toric data matches, also includes toric_type (str: ‘flop’, ‘weyl_g0’, ‘weyl_higher_genus’, or ‘other’) and toric_gv (int or None).

When compute_gvs=False and no gvs provided, returns a PartialClassification capturing the geometric narrowing.

Examples

>>> from cybir import diagnose_curve
>>> result = diagnose_curve(cy, [1, 0, -1])
>>> result['contraction_type']
ContractionType.FLOP

Skip GV computation, get partial result:

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

Notes

See arXiv:2212.10573 Section 4 for the classification algorithm.

ekc — Birational class orchestrator and result API

Contents

ekc — Birational class orchestrator and result API#