SEC.PoreEntryAnimation

SEC.PoreEntryAnimation#

SEC.PoreEntryAnimation.py

Single-molecule pore-entry animation: Knox sector geometry -> K_SEC -> LKM k.

Complements ColumnSimulation.py (multi-particle elution) with a focused view of what happens at the grain scale: one molecule diffusing through a 5-grain assembly, entering and exiting pore sectors, accumulating dwell statistics.

The simulation closes the loop:

geometry -> K_SEC -> LKM mass-transfer rate k -> SDM n_pi

Copyright (c) 2024-2025, Molass Community

run_simulation(r_mol=0.03, R_grain=0.2, num_pores=3, grain_centers=None, W=1.0, H=1.0, D=0.003, dt=0.002, n_steps=10000, v_drift=0.1, seed=42, k_a=0.0, k_d=1.0)#

Run a single-molecule Brownian simulation through a grain assembly.

Parameters:

  • r_mol (float) – Molecule radius.

  • R_grain (float) – Grain radius.

  • num_pores (int) – Number of pore sectors per grain. Determines sector half-angle alpha = pi / (2 * num_pores) and Knox pore radius R_p = R_grain * alpha.

  • grain_centers (list of (float, float), optional) – Centre coordinates of each grain. Defaults to 2+1+2 staggered layout.

  • W (float) – Simulation box width and height.

  • H (float) – Simulation box width and height.

  • D (float) – Diffusion coefficient.

  • dt (float) – Time step.

  • n_steps (int) – Number of simulation steps.

  • v_drift (float) – Downward mobile-phase drift speed (mobile-phase steps only).

  • seed (int) – Random seed.

  • k_a (float) – Langmuir adsorption rate (per unit time). 0 = pure SEC (no wall binding).

  • k_d (float) – Langmuir desorption rate (per unit time).

Returns:

positions : ndarray (n_steps+1, 2) states : ndarray (n_steps+1,) — grain index or -1 (mobile) wall_bound : ndarray (n_steps+1,) bool — True when wall-adsorbed entry_times : ndarray — simulation time of each pore entry dwell_times : ndarray — total pore dwell duration (free + adsorbed) entry_grain_arr : ndarray — which grain for each entry grains : list of NewGrain R_p : float — Knox pore radius rho : float — r_mol / R_p K_SEC_theory : float — Knox (1-rho)^2 approximation T_total : float K_ads : float — k_a / k_d equilibrium constant K_eff_theory : float — K_SEC_theory * (1 + K_ads)

Return type:

dict with keys

get_pore_entry_animation(r_mol=0.03, R_grain=0.2, num_pores=3, grain_centers=None, W=1.0, H=1.0, D=0.003, dt=0.002, n_steps=10000, v_drift=0.1, seed=42, k_a=0.0, k_d=1.0, n_frames=200, interval=40, close_plot=True)#

Create a pore-entry animation: single-molecule trajectory + live statistics.

Runs a Brownian simulation first, then wraps the pre-computed trajectory in a FuncAnimation with three panels:

  • Left2D grain assembly with molecule trajectory tail and colour-coded state

    (royalblue = mobile, orchid = free in pore, tomato = wall-adsorbed)

  • Top-right : Cumulative pore-entry count N(t) with linear-rate overlay

  • Bottom-right : Dwell-time histogram with exponential fit

Parameters:

  • r_mol – Passed directly to run_simulation.

  • R_grain – Passed directly to run_simulation.

  • num_pores – Passed directly to run_simulation.

  • grain_centers – Passed directly to run_simulation.

  • W – Passed directly to run_simulation.

  • H – Passed directly to run_simulation.

  • D – Passed directly to run_simulation.

  • dt – Passed directly to run_simulation.

  • n_steps – Passed directly to run_simulation.

  • v_drift – Passed directly to run_simulation.

  • seed – Passed directly to run_simulation.

  • k_a – Passed directly to run_simulation.

  • k_d – Passed directly to run_simulation.

  • n_frames (int) – Number of animation frames (default 200).

  • interval (int) – Delay between frames in milliseconds (default 40).

  • close_plot (bool) – If True, close the static figure after building the animation (prevents a duplicate static image appearing below the animation in notebooks).

Returns:

  • ani (matplotlib.animation.FuncAnimation)

  • sim (dict) – Simulation result from run_simulation (positions, states, dwell_times, …).