This PR refactors the AqueousEquilibrium class in musica.mechanism_configuration to use composition instead of inheritance from _AqueousEquilibrium, following the established pattern used in other reaction classes like Arrhenius, Troe, and Branched.

Changes Made

1. Composition Pattern Implementation

• Removed inheritance: Changed from class AqueousEquilibrium(_AqueousEquilibrium): to class AqueousEquilibrium:
• Added composition: The internal C++ instance is now held in self._instance = _AqueousEquilibrium()
• Property delegation: All attributes now use @property decorators that delegate to self._instance

2. Python/C++ Object Conversion

• Reactants/Products: Implemented seamless conversion between Python Species objects and C++ _ReactionComponent objects
• Type safety: Proper handling of coefficient tuples (float, Species) in reactants and products
• Phase handling: Supports both Phase objects and string names for aerosol_phase and aerosol_phase_water

3. Serialize Method Refactoring

• Instance method: Converted serialize() from static method to instance method operating on Python-visible data
• Backward compatibility: Added serialize_static() method for compatibility with C++ _AqueousEquilibrium objects
• Updated integration: Fixed mechanism_configuration.py to handle both Python and C++ objects correctly

4. Complete Property Coverage

All properties now properly delegate to self._instance:

• name, aerosol_phase, aerosol_phase_water
• reactants, products (with Python ↔ C++ conversion)
• A, C, k_reverse, other_properties
• type (returns ReactionType.AqueousEquilibrium)

Example Usage

import musica.mechanism_configuration as mc

# Create species and phase objects
water = mc.Species(name="H2O_aq")
aerosol = mc.Phase(name="aqueous_aerosol")
reactant = mc.Species(name="A")
product = mc.Species(name="B")

# Create aqueous equilibrium with composition pattern
aq_eq = mc.AqueousEquilibrium(
    name="my_equilibrium",
    aerosol_phase=aerosol,           # Accepts Phase object
    aerosol_phase_water=water,       # Accepts Species object  
    reactants=[(2.0, reactant)],     # Coefficient + Species tuple
    products=[product],              # Species object
    A=1.14e-2,
    C=2300.0,
    k_reverse=0.32
)

# All properties return Python objects
print(aq_eq.reactants)  # Returns List[Union[Species, Tuple[float, Species]]]
print(aq_eq.serialize())  # Instance method, operates on Python data

Pattern Consistency

This refactoring exactly matches the composition pattern established in:

• arrhenius.py
• troe.py
• branched.py
• condensed_phase_arrhenius.py

Benefits

• Clean separation: Public interface exposes only Python-native types
• Type safety: Proper conversion between Python and C++ objects
• Maintainability: Consistent pattern across all reaction classes
• Backward compatibility: Existing code continues to work with both object types

Fixes #445.

💬 Share your feedback on Copilot coding agent for the chance to win a $200 gift card! Click here to start the survey.