cometspec.collisions

Rotational-collision scaffolds and in-place collision application.

Routines

• canonical_diatomic_name() – canonicalize diatomic isotopologue labels.

• is_homonuclear_diatomic() – detect homonuclear diatomics.

• is_atomic_species() – detect atomic (non-diatomic) species such as Fe.

• diatomic_symmetry_class() – classify diatomics for collision selection rules.

• precompute_collision_scaffold() – build a collision scaffold from explicit lower-state columns in the transition table.

• precompute_collision_scaffold_fast() – same as above but with cached arrays for fast updates.

• apply_collisions_inplace() – apply collision rates to a matrix in place using the scaffold.

• apply_collisions_inplace_fast() – same as above but using cached arrays and reusable buffers for speed.

cometspec.collisions.canonical_diatomic_name(iso_name)

Return a canonical label for a diatomic isotopologue.

Atoms are sorted by (mass, element) so that labels like "13C12C" and "12C13C" collapse to the same canonical form ("12C13C"). Homonuclear labels with subscripts (e.g. "12C2") are preserved. If the label cannot be parsed as a diatomic, it is returned unchanged.

Parameters:

iso_name (str, optional) – Isotopologue label, or None.

Returns:

str or None – Canonicalized isotopologue label, or None if the input was None

cometspec.collisions.is_homonuclear_diatomic(iso_name)

Detect whether an isotopologue label denotes a homonuclear diatomic.

Homonuclear means the same element AND the same isotope on both atoms (e.g., "12C2", "13C2"). The mixed-isotope "12C13C" is treated as heteronuclear because the broken nuclear-permutation symmetry removes the even/odd-J restriction.

Parameters:

iso_name (str, optional) – Isotopologue label, or None.

Returns:

bool – True only for diatomics with two identical (mass, element) atoms; False otherwise (including unparseable or non-diatomic labels).

cometspec.collisions.is_atomic_species(iso_name)

Detect whether an isotopologue label denotes an atomic (non-diatomic) species.

Atomic species have no rotational structure and therefore no rotational collision channels in this framework. Labels containing "Fe" are treated as atomic (matching the packaged default Fe line list). Any label that parses to a single atom (e.g., "56Fe") is also classified as atomic.

Parameters:

iso_name (str, optional) – Isotopologue label, or None.

Returns:

bool – True for atomic species, False otherwise.

cometspec.collisions.diatomic_symmetry_class(iso_name)

Classify a diatomic isotopologue label for collision selection rules.

Parameters:

iso_name (str, optional) – Isotopologue label such as "12C2", "12C13C", "12C14N", or None.

Returns:

str – One of:

• "homonuclear" – two identical (mass, element) atoms (e.g., "12C2", "13C2"). Only \(|\Delta J| = 2\) collisions are physical (nuclear-spin manifold preserved).

• "same_element_heteronuclear" – same element, different isotopes (e.g., "12C13C"). Symmetry is broken so all J exist, but the underlying near-symmetric structure makes both \(|\Delta J| = 1\) and \(|\Delta J| = 2\) channels relevant.

• "heteronuclear" – different elements (e.g., "12C14N"). Treat as a generic heteronuclear with the caller-provided dJ_allowed (defaults to \(|\Delta J| = 1\) only).

• "unknown" – label could not be parsed as a diatomic.

cometspec.collisions.precompute_collision_scaffold(lines_out, idx_to_level, *, upper_id_col='upper_id', lower_id_col='lower_id', lower_es_col='lower_es', lower_v_col='lower_v', lower_J_col='lower_J', lower_sym_col='lower_sym', E_lower_cm1_col='E_lower_cm1', include_deltaJ0_parity_mix=True, require_X_only=True, iso_name=None, homonuclear=None, dJ_allowed=(1,))

Build a rotational-collision scaffold from explicit lower-state columns.

Parameters:

• lines_out (Any) – Annotated transition table.

• idx_to_level (dict) – Mapping from matrix index to level identifier.

• upper_id_col (str, optional, default "upper_id") – Upper-level ID column name.

• lower_id_col (str, optional, default "lower_id") – Lower-level ID column name.

• lower_es_col (str, optional, default "lower_es") – Lower electronic-state column name.

• lower_v_col (str, optional, default "lower_v") – Lower vibrational-state column name.

• lower_J_col (str, optional, default "lower_J") – Lower rotational-state column name.

• lower_sym_col (str, optional, default "lower_sym") – Lower-state symmetry/parity column name.

• E_lower_cm1_col (str, optional, default "E_lower_cm1") – Lower-state energy column name in cm^-1.

• include_deltaJ0_parity_mix (bool, optional, default True) – Allow Delta J = 0 collisions between sublevels with different sym label at the same J. Fires when either the molecule is truly heteronuclear (different elements, e.g. CN, OH) OR the isotopologue has at least one nucleus with nonzero spin (hyperfine structure, e.g. 13C2, 12C13C). Ignored only for strictly zero-hyperfine homonuclear species like 12C2.

• require_X_only (bool, optional, default True) – Restrict collisions to the lower electronic state. The lower state is auto-detected as the lower_es label whose minimum E_lower_cm1 is smallest, so any spectroscopic notation works ("X", "X1Sigmag+", etc.).

• iso_name (str, optional, default None) – Optional isotopologue label (e.g., "12C2", "13C2", "12C13C", "12C14N") used to auto-classify the diatomic via diatomic_symmetry_class(). Drives the |Delta J| rule:

  • homonuclear -> \(|\Delta J|=2\) only

  • same-element heteronuclear (e.g., "12C13C") -> \(|\Delta J|=1\) and \(|\Delta J|=2\)

  • heteronuclear different elements (e.g., "12C14N") -> uses dJ_allowed, which defaults to \(|\Delta J|=1\) only (Arbitrary choice).

  Ignored when homonuclear is given explicitly.

• homonuclear (bool, optional, default None) – Explicit override for nuclear symmetry. True forces |Delta J| = 2 only and disables include_deltaJ0_parity_mix (preserves nuclear-spin manifold). False uses dJ_allowed. None auto-detects from iso_name.

• dJ_allowed (Sequence[int], optional, default (1,)) – Allowed |Delta J| values for the heteronuclear different-element case (e.g., CN). Defaults to (1,) to match Manfroid 2009 [1]. Ignored for homonuclear (forced to (2,)) and for same-element heteronuclear (forced to (1, 2)).

Returns:

dict – Scaffold dictionary mapping pre-computed collisional pair data to NumPy arrays. All arrays share the same length (one entry per allowed collisional pair) and are aligned by index. Keys:

• iu (numpy.ndarray of int) – Matrix index of the upper level of each collisional pair.

• il (numpy.ndarray of int) – Matrix index of the lower level of each collisional pair.

• gu (numpy.ndarray of float) – Degeneracy of the upper level.

• gl (numpy.ndarray of float) – Degeneracy of the lower level.

• dE (numpy.ndarray of float) – Energy gap \(E_u - E_l\) between the two levels, in \(\mathrm{cm}^{-1}\) (always non-negative by construction).

Raises:

ValueError – If required columns are missing.

References

[1]

Manfroid, J., Jehin, E., Hutsemékers, D., et al. 2009, A&A, 503, 613 (link)

cometspec.collisions.precompute_collision_scaffold_fast(*args, **kwargs)

Build collision scaffold and add cached arrays for fast updates.

Parameters:

• args (tuple) – Positional arguments forwarded to precompute_collision_scaffold().

• kwargs (dict) – Keyword arguments forwarded to precompute_collision_scaffold().

Returns:

dict – Collision scaffold with dE_over_k_K and gu_over_gl caches.

cometspec.collisions.apply_collisions_inplace(M, scaffold, *, Q, T)

Apply rotational-collision rates to a matrix in place.

Parameters:

• M (numpy.ndarray) – Rate matrix to modify.

• scaffold (dict[str, numpy.ndarray]) – Collision scaffold containing iu, il, gu, gl, and dE.

• Q (float) – Downward collision rate scale.

• T (float) – Kinetic temperature in K.

Returns:

numpy.ndarray – The modified matrix M.

cometspec.collisions.apply_collisions_inplace_fast(M, scaffold, *, Q, T, Cup_work)

Apply collisions in place using cached arrays and reusable buffers.

Parameters:

• M (numpy.ndarray) – Rate matrix to modify.

• scaffold (dict[str, numpy.ndarray]) – Collision scaffold with dE_over_k_K and gu_over_gl.

• Q (float) – Downward collision rate scale.

• T (float) – Kinetic temperature in K.

• Cup_work (numpy.ndarray) – Reusable working array for upward rates.

Returns:

numpy.ndarray – The modified matrix M.

cometspec.collisions.HC_OVER_K_B_KCM

Planck constant times speed of light over Boltzmann constant, in K*cm.