uclchem.makerates.network_compat
================================

.. py:module:: uclchem.makerates.network_compat

.. autoapi-nested-parse::

   Compatibility layer for old Network and LoadedNetwork APIs.

   This module provides backward compatibility wrappers for the old Network
   and LoadedNetwork classes. It's kept separate and NOT imported by default
   to allow for a clean breaking change in v4.0.

   When ready to deprecate, this can be imported in __init__.py to provide
   warnings and migration paths.



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

Classes
~~~~~~~

.. autoapisummary::

   uclchem.makerates.network_compat.LoadedNetwork
   uclchem.makerates.network_compat.NetworkState



Functions
~~~~~~~~~

.. autoapisummary::

   uclchem.makerates.network_compat.Network



.. py:class:: LoadedNetwork

   Backward compatible LoadedNetwork class.

   This class provides compatibility with the old LoadedNetwork API.
   It redirects to appropriate Network factory methods.

   Deprecated:
       Use Network.from_csv(), Network.from_lists(), or the module-level
       factory functions instead.


   Create a network using old LoadedNetwork API.

   :param cls: Not used
   :type cls: Any
   :param species: List of Species objects (use with reactions).
                   Default = None.
   :type species: list[Species] | None
   :param reactions: List of Reaction objects (use with species).
                     Default = None.
   :type reactions: list[Reaction] | None
   :param species_filepath: Path to species CSV (use with reactions_filepath).
                            Default = None.
   :type species_filepath: str | Path | None
   :param reactions_filepath: Path to reactions CSV (use with species_filepath).
                              Default = None.
   :type reactions_filepath: str | Path | None

   :returns: Network instance created via appropriate factory method
   :rtype: NewNetwork

   :raises ValueError: If both `species` and `reactions` and file paths are specified,
       or if only species or reactions is provided.

   .. rubric:: Examples

   >>> # Build with validation
   >>> from uclchem.makerates.io_functions import read_species_file, read_reaction_file
   >>> from uclchem.utils import UCLCHEM_ROOT_DIR
   >>>
   >>> species_path = UCLCHEM_ROOT_DIR / "species.csv"
   >>> reactions_path = UCLCHEM_ROOT_DIR / "reactions.csv"

   >>> species_list, user_defined_bulk = read_species_file(species_path)
   >>> reactions_list, dropped_reactions = read_reaction_file(
   ...     reactions_path, species_list, "UCL"
   ... )

   >>> # Old style (deprecated)
   >>> network = LoadedNetwork()
   >>> network = LoadedNetwork(
   ...     species_filepath=species_path,
   ...     reactions_filepath=reactions_path
   ... )
   >>> network = LoadedNetwork(species=species_list, reactions=reactions_list)

   >>> # New style (recommended)
   >>> from uclchem.makerates.network import Network
   >>> network = Network.from_csv()
   >>> network = Network.from_csv(species_path, reactions_path)
   >>> network = Network.from_lists(species_list, reactions_list)
   >>> # or use module-level functions
   >>> from uclchem.makerates.network import load_network_from_csv, create_network
   >>> network = load_network_from_csv()
   >>> network = create_network(species_list, reactions_list)


.. py:class:: NetworkState

   Backward compatible NetworkState class.

   This class provides compatibility with the old NetworkState API from
   uclchem.advanced. It redirects to ``RuntimeNetwork()`.

   Deprecated:
       Use ``RuntimeNetwork()`` instead.


   Create a network with Fortran interface using old NetworkState API.

   :param cls: Not used
   :type cls: Any

   :returns: Network instance with Fortran interface
   :rtype: Network

   .. rubric:: Examples

   >>> # Old style (deprecated)
   >>> from uclchem.advanced import NetworkState
   >>> network = NetworkState()
   >>> network._network.alpha[0] = 999.0

   >>> # New style (recommended)
   >>> from uclchem.advanced.runtime_network import RuntimeNetwork
   >>>
   >>> network = RuntimeNetwork()
   >>> network.modify_reaction_parameters(0, alpha=999.0)
   >>> # or for direct access
   >>> network._fortran.alpha[0] = 999.0
   >>>


.. py:function:: Network(species: list[uclchem.makerates.species.Species] | None = None, reactions: list[uclchem.makerates.reaction.Reaction] | None = None, **kwargs: Any) -> uclchem.makerates.network.Network

   Backward compatible Network constructor.

   This function provides compatibility with the old Network class constructor.
   It redirects to the appropriate new factory method based on the arguments.

   Deprecated:
       Use Network.build() or build_network() instead for new code.

   :param species: List of Species objects. Default = None.
   :type species: list[Species] | None
   :param reactions: List of Reaction objects. Default = None.
   :type reactions: list[Reaction] | None
   :param \*\*kwargs: Build options (gas_phase_extrapolation, etc.)
   :type \*\*kwargs: Any

   :returns: Network instance created via build_network()
   :rtype: NewNetwork

   :raises ValueError: If `species` or `reactions` is None.

   .. rubric:: Examples

   >>> # Build with validation
   >>> 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",
   ... )

   >>> # Old style (deprecated)
   >>> network = Network(species_list, reactions_list, gas_phase_extrapolation=True)

   >>> # New style (recommended)
   >>> from uclchem.makerates.network import Network, build_network
   >>> network = Network.build(species_list, reactions_list, gas_phase_extrapolation=True)
   >>> # or
   >>> network = build_network(species_list, reactions_list, gas_phase_extrapolation=True)