uclchem.makerates.network_builder
=================================

.. py:module:: uclchem.makerates.network_builder

.. autoapi-nested-parse::

   NetworkBuilder - Handles complex network construction logic.

   This module extracts the build-time complexity from the Network class,
   providing a clean separation between:
   - Network: Data container with unified interface
   - NetworkBuilder: Build-time validation and automatic reaction generation



Module Contents
---------------

Classes
~~~~~~~

.. autoapisummary::

   uclchem.makerates.network_builder.NetworkBuilder




Attributes
~~~~~~~~~~

.. autoapisummary::

   uclchem.makerates.network_builder.logger


.. py:class:: NetworkBuilder(species: list[uclchem.makerates.species.Species], reactions: list[uclchem.makerates.reaction.Reaction], user_defined_bulk: list | None = None, gas_phase_extrapolation: bool = False, add_crp_photo_to_grain: bool = False, derive_reaction_exothermicity: list[str] | None = None, database_reaction_exothermicity: list[str | pathlib.Path] | None = None)

   Builder for constructing complex chemical networks.

   Handles all build-time operations:
   - Input validation
   - Automatic freeze-out reactions
   - Automatic bulk species and reactions
   - Automatic desorption reactions
   - Branching ratio validation and correction
   - Temperature range collision detection
   - Gas-phase reaction extrapolation
   - Reaction exothermicity calculation

   This class separates the complex build logic from the Network data container,
   making the code more maintainable and testable.

   .. rubric:: Examples

   >>> from uclchem.makerates.io_functions import read_species_file, read_reaction_file
   >>> from uclchem.utils import UCLCHEM_ROOT_DIR
   >>>
   >>> species_list, user_defined_bulk = read_species_file(
   ...     UCLCHEM_ROOT_DIR / "../../Makerates/data/default/default_species.csv"
   ... )
   >>> reactions_list, dropped_reactions = read_reaction_file(
   ...     UCLCHEM_ROOT_DIR / "../../Makerates/data/default/default_grain_network.csv",
   ...     species_list,
   ...     "UCL",
   ... )
   >>> builder = NetworkBuilder(
   ...     species=species_list,
   ...     reactions=reactions_list,
   ...     gas_phase_extrapolation=True,
   ...     add_crp_photo_to_grain=True
   ... )
   >>> network = builder.build()

   Initialize the network builder.

   :param species: List of chemical species
   :type species: list[Species]
   :param reactions: List of chemical reactions
   :type reactions: list[Reaction]
   :param user_defined_bulk: User-specified bulk species (optional) (Default value = None)
   :type user_defined_bulk: list | None
   :param gas_phase_extrapolation: Extrapolate gas-phase temperature (default: False)
   :type gas_phase_extrapolation: bool
   :param add_crp_photo_to_grain: Add CRP/PHOTON to grain (default: False)
   :type add_crp_photo_to_grain: bool
   :param derive_reaction_exothermicity: Reaction types to calculate exothermicity for (Default value = None)
   :type derive_reaction_exothermicity: list[str] | None
   :param database_reaction_exothermicity: Custom exothermicity database files (Default value = None)
   :type database_reaction_exothermicity: list[str | Path] | None

   :raises ValueError: If duplicate species are provided.


   .. py:method:: build() -> uclchem.makerates.network.Network

      Build the network with all validations and automatic additions.

      This method orchestrates all build steps in the correct order:
      1. Create initial network from inputs
      2. Add electron species
      3. Check and handle freeze/desorb species
      4. Add automatic reactions (freeze, bulk, desorb, chemdes)
      5. Validate branching ratios
      6. Apply optional features (extrapolation, exothermicity)
      7. Sort and filter final network

      :returns: Fully built and validated network
      :rtype: Network



   .. py:attribute:: add_crp_photo_to_grain
      :value: False



   .. py:attribute:: database_reaction_exothermicity
      :value: None



   .. py:attribute:: derive_reaction_exothermicity
      :value: None



   .. py:attribute:: enthalpies_present
      :value: False



   .. py:attribute:: excited_species
      :value: False



   .. py:attribute:: gas_phase_extrapolation
      :value: False



   .. py:attribute:: input_reactions


   .. py:attribute:: input_species


   .. py:property:: network
      :type: uclchem.makerates.network.Network


      Return the network under construction.

      :returns: The network being built.
      :rtype: Network

      :raises RuntimeError: If accessed before :meth:`build` has created the network.


   .. py:attribute:: user_defined_bulk
      :value: []



.. py:data:: logger