petitRADTRANS.chemistry.core ============================ .. py:module:: petitRADTRANS.chemistry.core Attributes ---------- .. autoapisummary:: petitRADTRANS.chemistry.core.get_easychem_abundances petitRADTRANS.chemistry.core.INVALID_VALUE petitRADTRANS.chemistry.core._ISOTOPE_RATIO_SPECS Functions --------- .. autoapisummary:: petitRADTRANS.chemistry.core._get_active_abundance_profile_mode petitRADTRANS.chemistry.core._build_pressure_varying_mass_fraction_profile petitRADTRANS.chemistry.core._normalize_parameter_mapping petitRADTRANS.chemistry.core._get_parameter_alias_value petitRADTRANS.chemistry.core._get_static_bool_parameter petitRADTRANS.chemistry.core._has_truthy_parameter petitRADTRANS.chemistry.core._get_cached_cloud_metadata petitRADTRANS.chemistry.core._build_cloud_metadata petitRADTRANS.chemistry.core._has_explicit_cloud_base petitRADTRANS.chemistry.core._resolve_cloud_base_pressure petitRADTRANS.chemistry.core._resolve_cloud_fsed petitRADTRANS.chemistry.core._resolve_cloud_abundance petitRADTRANS.chemistry.core.resolve_cloud_base_pressures petitRADTRANS.chemistry.core._contains_isotope petitRADTRANS.chemistry.core._replace_isotope petitRADTRANS.chemistry.core._build_isotopologue_ratio_mass_fractions petitRADTRANS.chemistry.core._simplify_species_in_original_order petitRADTRANS.chemistry.core._resolve_chemistry_mode petitRADTRANS.chemistry.core._build_easychem_mass_fractions petitRADTRANS.chemistry.core.calculate_gas_mass_fractions petitRADTRANS.chemistry.core.calculate_cloud_mass_fractions petitRADTRANS.chemistry.core.get_abundances petitRADTRANS.chemistry.core.get_abundances_from_legacy_dict petitRADTRANS.chemistry.core.get_abundances_legacy Module Contents --------------- .. py:data:: get_easychem_abundances :value: None .. py:data:: INVALID_VALUE .. py:data:: _ISOTOPE_RATIO_SPECS .. py:function:: _get_active_abundance_profile_mode(species_name, parameters) Return the enabled pressure-varying abundance profile mode for a species. Args: species_name: Species name used to look up profile-control parameters. parameters: Mapping of model parameters. Returns: The first enabled profile mode among ``"stepped"``, ``"linear"``, and ``"cubic"``, or ``None`` if no mode is active. .. py:function:: _build_pressure_varying_mass_fraction_profile(pressures, species_name, parameters, profile_mode) Build a pressure-varying mass-fraction profile for one species. Args: pressures: Pressure grid on which to evaluate the abundance profile. species_name: Species name used to resolve interpolation nodes from ``parameters``. parameters: Mapping of model parameters. profile_mode: Profile-construction mode understood by ``build_abundance_profile``. Returns: A mass-fraction profile sampled on ``pressures``. .. py:function:: _normalize_parameter_mapping(parameters) Convert plain or legacy parameter values to a plain-value mapping. .. py:function:: _get_parameter_alias_value(parameters, *names, default=None) Return the first non-``None`` parameter value among the provided aliases. .. py:function:: _get_static_bool_parameter(parameter_name, parameter_value) -> bool Return a Python bool for structural chemistry flags. Chemistry-mode and profile-selection flags drive Python control flow, so they must remain static scalars when the chemistry path is traced. .. py:function:: _has_truthy_parameter(parameters, *names) Return whether any aliased parameter is explicitly enabled. .. py:function:: _get_cached_cloud_metadata(cloud_species) Return cached ``(opacity_name, base_name)`` pairs for cloud species. .. py:function:: _build_cloud_metadata(cloud_species) Return ``(opacity_name, base_name)`` pairs for cloud species. .. py:function:: _has_explicit_cloud_base(parameter_keys, cloud_name) .. py:function:: _resolve_cloud_base_pressure(cloud_name, *, pressures, temperatures, metallicity, co_ratio, parameters, parameter_keys, mean_molar_mass, has_equilibrium_cloud_base) .. py:function:: _resolve_cloud_fsed(cloud_name, parameters, parameter_keys) .. py:function:: _resolve_cloud_abundance(cloud, cloud_name, *, metallicity, co_ratio, parameters, parameter_keys, mass_fractions, use_easychem, zero_profile, one_profile) .. py:function:: resolve_cloud_base_pressures(pressures: jax.typing.ArrayLike, temperatures: jax.typing.ArrayLike, parameters: dict, line_species: tuple, cloud_species: tuple, filling_species: tuple | dict | None = None, **kwargs) Resolve cloud-base pressures without constructing full cloud profiles. This helper is intended for adaptive pressure-grid setup. When cloud-base pressures are explicitly parameterized, it returns them directly without running chemistry. Otherwise it computes only the gas-composition state needed to derive mean molar masses and then resolves the cloud bases. .. py:function:: _contains_isotope(isotopologue_name: str, isotope: str) -> bool Return whether an isotopologue name contains a specific isotope token. .. py:function:: _replace_isotope(isotopologue_name: str, from_isotope: str, to_isotope: str) -> str Replace isotope tokens while preserving token separators and element counts. .. py:function:: _build_isotopologue_ratio_mass_fractions(*, line_species, parameters, mass_fractions_chemical_table) Build rare-isotopologue profiles from isotope-ratio parameters. For each supported isotope ratio, when both a rare isotopologue and its corresponding main isotopologue are present in ``line_species``, this helper defines the rare profile as ``ratio * main_profile``. .. py:function:: _simplify_species_in_original_order(line_species) Return simplified species names without reordering the input sequence. .. py:function:: _resolve_chemistry_mode(parameters) Resolve free, precalculated-equilibrium, and full-easyChem chemistry modes. The parameter mapping drives chemistry selection as follows: - ``use_easychem`` or ``use_exoatmos`` explicitly enables the full easyChem calculation. - Otherwise, a metallicity parameter (``metallicity``, ``M/H``, or ``Fe/H``) selects the built-in precalculated equilibrium table by default. - If neither signal is present, the caller stays on the free-chemistry path. .. py:function:: _build_easychem_mass_fractions(pressures, temperatures, parameters, line_species, cloud_species, metallicity, co_ratio, carbon_quench_pressure, use_full_easychem, exo_atmos, atomic_mass_fractions, adaptive_mesh_refinement) Build mass fractions from the explicit full easyChem chemistry path. .. py:function:: calculate_gas_mass_fractions(pressures, temperatures=None, imposed_mass_fractions=None, line_species=None, cloud_species=None, filling_species=None, use_equilibrium_chemistry=False, metallicity=None, co_ratio=0.55, carbon_quench_pressure=None, exo_atmos=None, atomic_mass_fractions=None, **kwargs) Build and normalize per-layer gas mass-fraction profiles. The function combines explicitly imposed gas abundances, optional pre-calculated equilibrium chemistry, and background filling species so that each atmospheric layer sums to unity. Args: pressures: Pressure grid for the atmospheric layers. temperatures: Temperature profile on the same grid as ``pressures``. Required when interpolating the equilibrium chemistry table. imposed_mass_fractions: Mapping of species names to imposed mass fractions. Scalar inputs are broadcast over the pressure grid. Negative values are interpreted as base-10 logarithmic mass fractions. line_species: Gas-opacity species names. These are used to reconcile opacity names with chemistry-table names and to discover pressure-varying profile controls. cloud_species: Cloud-opacity species names. Accepted for API compatibility with the broader chemistry pipeline; they are not used directly in the active gas-fraction path. filling_species: Optional fill-specification for background gases. This may be ``None``, a species name, an iterable of species names, or a mapping of species names to fill weights. use_equilibrium_chemistry: If ``True``, use the built-in precalculated equilibrium chemistry table together with ``metallicity`` and ``co_ratio``. The explicit full easyChem path is resolved upstream in :func:`get_abundances`. metallicity: Metallicity passed to the pre-calculated equilibrium chemistry table. When provided, equilibrium gas abundances are interpolated. co_ratio: Carbon-to-oxygen ratio used with the equilibrium chemistry table. carbon_quench_pressure: Optional quench pressure forwarded to the equilibrium chemistry interpolation. exo_atmos: Compatibility argument reserved for legacy/easychem callers. atomic_mass_fractions: Compatibility argument reserved for legacy/easychem callers. **kwargs: Additional keyword arguments. If a ``parameters`` mapping is present, it is used to detect pressure-varying abundance-profile controls. Returns: A tuple ``(mass_fractions, m_sum_total)`` containing the per-species mass-fraction profiles and the total mass-fraction sum in each layer. .. py:function:: calculate_cloud_mass_fractions(pressures, temperatures, metallicity, co_ratio, cloud_species, parameters, mass_fractions, mean_molar_mass, adaptive_mesh_refinement=False, use_easychem=False) Add cloud abundance profiles and cloud-base metadata to a composition. Args: pressures: Pressure grid for the atmospheric layers. temperatures: Temperature profile on the same grid as ``pressures``. metallicity: Metallicity used when equilibrium cloud abundances or cloud bases are requested. co_ratio: Carbon-to-oxygen ratio used with equilibrium cloud calculations. cloud_species: Condensate-opacity species names to evaluate. parameters: Mapping of plain model parameter values controlling cloud abundances, cloud bases, and sedimentation efficiencies. mass_fractions: Existing species mass fractions. This mapping is updated in place with the computed cloud profiles. mean_molar_mass: Mean molar-mass profile used when computing cloud-base pressures. adaptive_mesh_refinement: Compatibility argument retained for the public API. The current cloud path returns the identity pressure grid. use_easychem: If ``True``, copy cloud abundances directly from a full easyChem composition instead of constructing sedimented cloud profiles. Returns: A tuple ``(mass_fractions, p_bases, pressure_indices)`` containing the updated mass fractions, cloud-base pressures keyed by cloud name, and the pressure-grid indices used by the cloud path. .. py:function:: get_abundances(pressures: jax.typing.ArrayLike, temperatures: jax.typing.ArrayLike, parameters: dict, line_species: tuple, cloud_species: tuple, filling_species: tuple | dict = None, adaptive_mesh_refinement: bool = False, **kwargs) Assemble gas and cloud abundances for a pressure-temperature profile. This function resolves the requested chemistry mode from ``parameters``, computes gas mass fractions, derives the mean molar mass, and optionally adds condensate abundances and cloud-base information. Args: pressures: Pressure grid for the atmospheric layers. temperatures: Temperature profile on the same grid as ``pressures``. parameters: Mapping of plain model parameter values. Supported keys depend on the selected chemistry and cloud mode and may include equilibrium-chemistry controls, directly imposed abundances, pressure-varying profile flags, cloud abundance parameters, and cloud-base parameters. line_species: Gas-opacity species names. cloud_species: Condensate-opacity species names. filling_species: Optional background fill-specification forwarded to ``calculate_gas_mass_fractions``. If omitted, a default H2/He fill is used. adaptive_mesh_refinement: Forwarded to ``calculate_cloud_mass_fractions``. The current cloud path returns the identity pressure grid. **kwargs: Additional keyword arguments forwarded to ``calculate_gas_mass_fractions``. Returns: A tuple ``(mass_fractions, mean_molar_mass, pressure_indices, p_bases)`` containing the species mass fractions, the mean molar-mass profile, the selected pressure-grid indices, and the cloud-base pressures. Chemistry-mode selection: ``get_abundances`` distinguishes three chemistry modes from the plain parameter mapping: - free chemistry: no equilibrium selector is present; - precalculated equilibrium chemistry: selected by default when a metallicity parameter such as ``Fe/H``, ``M/H``, or ``metallicity`` is present, or when ``use_equilibrium_chemistry=True``; - full easyChem chemistry: selected only when ``use_easychem`` or ``use_exoatmos`` is explicitly truthy. An explicit full easyChem request takes precedence over the default precalculated equilibrium-table path. .. py:function:: get_abundances_from_legacy_dict(pressures: jax.typing.ArrayLike, temperatures: jax.typing.ArrayLike, parameters: dict, line_species: tuple, cloud_species: tuple, filling_species: tuple | dict = None, adaptive_mesh_refinement: bool = False, **kwargs) Legacy wrapper for :func:`get_abundances`. Converts a legacy parameter dictionary (values accessed via ``.value``) to a plain-value mapping before forwarding to :func:`get_abundances`. Args: pressures: Pressure grid for the atmospheric layers. temperatures: Temperature profile on the same grid as ``pressures``. parameters: Legacy parameter mapping whose values expose a ``.value`` attribute. line_species: Gas-opacity species names. cloud_species: Condensate-opacity species names. filling_species: Optional background fill-specification forwarded to :func:`get_abundances`. adaptive_mesh_refinement: Forwarded unchanged to :func:`get_abundances`. **kwargs: Additional keyword arguments forwarded to :func:`get_abundances`. Returns: The same tuple returned by :func:`get_abundances`. .. py:function:: get_abundances_legacy(pressures, temperatures, line_species, cloud_species, parameters, adaptive_mesh_refinement=False) Legacy abundance pipeline retained for compatibility. This historical implementation supports the older parameter objects whose values are accessed via ``.value`` and preserves the original free-chemistry, equilibrium-chemistry, and cloud-handling flow. Args: pressures: Pressure grid for the atmospheric layers. temperatures: Temperature profile on the same grid as ``pressures``. line_species: Gas-opacity species names. cloud_species: Condensate-opacity species names. parameters: Legacy parameter mapping whose values are accessed via ``.value``. Supported keys depend on the selected legacy chemistry and cloud mode. adaptive_mesh_refinement: Retained for API compatibility. Legacy adaptive pressure-grid expansion has been removed and the input grid is always used. # Find high resolution pressure grid and indices Returns: A tuple ``(abundances, mmw, pressure_indices, p_bases)`` containing the species mass fractions, the mean molar-mass profile, the selected pressure-grid indices, and the cloud-base pressures.