Microscopic Gating Documentation
=================================

A minimal microscopic model for chemically gated bridging.

This package implements a theoretical framework for understanding how chemical
binding controls transport through gated structures at the microscopic scale.
The model connects molecular adsorption to macroscopic transport properties
through a chain of physical mechanisms.

.. contents:: Table of Contents
   :depth: 3
   :local:

Core Concept
------------

The model describes how particle binding to receptor sites creates transient
"bridges" that can either open or close transport pathways. The key insight is
that transport is controlled by the statistics of bridge formation, which
depends on:

1. **Adsorption isotherms** - How occupancy depends on concentration
2. **Gating functions** - How bridge probability depends on occupancy
3. **Bridge statistics** - Distribution of bridge counts
4. **Escape dynamics** - How bridges affect transport rates

The full chain is:

   Langmuir/Hill occupancy → bridging probability → bridge-number distribution → gate open/closed

Quick Start
-----------

.. code-block:: python

   from microscopic_gating import MicroscopicGatingModel, LangmuirIsotherm
   from microscopic_gating.geometry import ConstantContactProbability
   from microscopic_gating.gating import SymmetricGating
   from microscopic_gating.types import SitePairCount

   # Create isotherm
   isotherm = LangmuirIsotherm(K=1.0)

   # Create symmetric gating
   gating = SymmetricGating(isotherm)

   # Create full model
   model = MicroscopicGatingModel(
       gating=gating,
       contact=ConstantContactProbability(chi=0.5),
       kappa_B=0.8,
       site_pairs=SitePairCount(M=10, N_acc=5)
   )

   # Calculate gate probabilities
   import numpy as np
   phi = np.logspace(-2, 2, 100)
   P_open = model.P_open(phi)
   P_closed = model.P_closed(phi)

Key Components
--------------

Adsorption & Binding
~~~~~~~~~~~~~~~~~~~~

- :class:`~microscopic_gating.adsorption.LangmuirIsotherm` - Standard Langmuir adsorption
- :class:`~microscopic_gating.adsorption.HillIsotherm` - Hill isotherm with cooperativity

Gating Mechanisms
~~~~~~~~~~~~~~~~~

- :class:`~microscopic_gating.gating.SymmetricGating` - Symmetric binding (θ(1-θ))
- :class:`~microscopic_gating.gating.AsymmetricGating` - Asymmetric binding (θ_P(1-θ_N))

Statistical Models
~~~~~~~~~~~~~~~~~~

- :class:`~microscopic_gating.statistics.BridgeCountModel` - Poisson bridge statistics
- :class:`~microscopic_gating.statistics.GateModel` - Gate open/closed probabilities

Transport & Dynamics
~~~~~~~~~~~~~~~~~~~~

- :class:`~microscopic_gating.transport.JumpDiffusion` - Jump diffusion mapping
- :class:`~microscopic_gating.transport.PoissonEscapeAveraging` - Escape rate averaging
- :class:`~microscopic_gating.transport.ConcentrationDependentDiffusion` - D(φ) model

Phase Behavior
~~~~~~~~~~~~~~

- :class:`~microscopic_gating.phase_boundaries.DomePhaseBoundaries` - Dome-shaped phase boundaries
- :class:`~microscopic_gating.phase_boundaries.CaptureIslandWindow` - Capture island analysis

Unified Models
~~~~~~~~~~~~~~

- :class:`~microscopic_gating.unified_phase.UnifiedModel` - Complete unified framework
- :class:`~microscopic_gating.unified_phase.SuppressionCaptureIsland` - Suppression effects

Theory Background
-----------------

For detailed theoretical derivations from statistical mechanics:

.. toctree::
   :maxdepth: 2

   theory_background

API Reference
-------------

.. toctree::
   :maxdepth: 2
   :caption: API Reference

   api/adsorption
   api/gating
   api/statistics
   api/transport
   api/phase_boundaries
   api/unified_phase
   api/model
   api/types

Indices and tables
==================

* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`