VLBVariant — Bell, FENE-P & Temperature¶

Quick Reference¶

Model Summary¶
Model Class	`VLBVariant`
Physics	VLB transient network with force-dependent breakage, finite extensibility, and/or temperature dependence
Key Parameters	\(G_0, k_d^0, \nu\) (Bell), \(L_{\max}\) (FENE), \(E_a, T_{\text{ref}}\) (Temperature)
Protocols	FLOW_CURVE, STARTUP, RELAXATION, CREEP, OSCILLATION, LAOS
Key Features	Shear thinning, stress overshoot, bounded extensional viscosity, Arrhenius scaling
Reference	Vernerey, Long & Brighenti (2017). JMPS 107, 1-20; Bell (1978). Science 200, 618

Import:

from rheojax.models import VLBVariant

Overview¶

VLBVariant extends the VLB transient network with three composable physics options:

Bell breakage — Force-dependent dissociation rate that produces shear thinning, stress overshoot, and nonlinear LAOS response
FENE-P stress — Finite extensibility that bounds the extensional viscosity and adds strain hardening
Temperature dependence — Arrhenius scaling of \(k_d\) and thermal modulus \(G_0(T)\)

These can be combined freely through constructor flags. With all flags off (breakage="constant", stress_type="linear", temperature=False), VLBVariant exactly reproduces VLBLocal.

Constructor Flags¶

model = VLBVariant(
    breakage="constant",     # or "bell"
    stress_type="linear",    # or "fene"
    temperature=False,       # or True
)

Parameters¶

Parameter	When Present	Units	Description
\(G_0\)	Always	Pa	Network modulus
\(k_d^0\)	Always	1/s	Unstressed dissociation rate
\(\nu\)	`breakage="bell"`	—	Force sensitivity (0 = Newtonian, >1 = shear thinning)
\(L_{\max}\)	`stress_type="fene"`	—	Maximum chain extensibility
\(E_a\)	`temperature=True`	J/mol	Activation energy for bond dissociation
\(T_{\text{ref}}\)	`temperature=True`	K	Reference temperature

Bell Breakage Model¶

Theory¶

The Bell model (1978) makes the dissociation rate force-dependent:

\[k_d(\boldsymbol{\mu}) = k_d^0 \exp\!\left(\nu \cdot (\lambda_c - 1)\right)\]

where \(\lambda_c = \sqrt{\text{tr}(\boldsymbol{\mu})/3}\) is the normalized average chain stretch. For the detailed theory including slip-bond and catch-bond formulations, see VLB Advanced Theory & Numerical Methods.

Physical effects:

Shear thinning: \(\eta(\dot\gamma)\) decreases with shear rate because stretched chains break faster, reducing effective cross-link density
Stress overshoot: At startup, transient stretch exceeds steady state, causing \(\sigma_{\max} > \sigma_{ss}\) at high Weissenberg numbers
Nonlinear LAOS: Higher harmonics \(I_3/I_1 > 0\) (unlike constant \(k_d\) which is purely linear)
Faster relaxation: Pre-stretched chains relax faster than predicted by the equilibrium \(k_d^0\)

Usage¶

from rheojax.models import VLBVariant

model = VLBVariant(breakage="bell")
model.parameters.set_value("G0", 1000.0)
model.parameters.set_value("k_d_0", 1.0)
model.parameters.set_value("nu", 5.0)

# Shear-thinning flow curve
gamma_dot = np.logspace(-2, 2, 50)
sigma = model.predict_flow_curve(gamma_dot)

# Stress overshoot in startup
t = np.linspace(0.01, 20, 200)
sigma_t = model.simulate_startup(t, gamma_dot=10.0)

FENE-P Finite Extensibility¶

Theory¶

The FENE-P (finitely extensible nonlinear elastic with Peterlin closure) model replaces the linear Hookean spring with a nonlinear spring:

\[\boldsymbol{\sigma} = G_0 \cdot f(\text{tr}(\boldsymbol{\mu})) \cdot (\boldsymbol{\mu} - \mathbf{I})\]

\[f = \frac{L_{\max}^2}{L_{\max}^2 - \text{tr}(\boldsymbol{\mu}) + 3}\]

At equilibrium (\(\boldsymbol{\mu} = \mathbf{I}\)), \(f = 1\) and the stress reduces to the linear Hookean form. As chains stretch toward their maximum extensibility, \(f \to \infty\), creating a strongly nonlinear stress response.

Physical effects:

Bounded extensional viscosity: The Trouton ratio remains finite even at high extension rates (resolves the Hookean singularity at \(\dot\varepsilon = k_d/2\))
Strain hardening: Stress increases super-linearly with strain
Large \(L_{\max}\) recovers linear: At \(L_{\max} \to \infty\), FENE-P reduces to the linear Hookean model

Usage¶

model = VLBVariant(stress_type="fene")
model.parameters.set_value("G0", 1000.0)
model.parameters.set_value("k_d_0", 1.0)
model.parameters.set_value("L_max", 10.0)

Temperature Dependence¶

Theory¶

Arrhenius temperature scaling of the dissociation rate:

\[k_d(T) = k_d^0 \exp\!\left(-\frac{E_a}{R}\left(\frac{1}{T} - \frac{1}{T_{\text{ref}}}\right)\right)\]

Thermal modulus scaling (rubber elasticity):

\[G_0(T) = G_0^{\text{ref}} \cdot \frac{T}{T_{\text{ref}}}\]

At \(T = T_{\text{ref}}\), both reduce to their reference values.

Usage¶

model = VLBVariant(temperature=True)
model.parameters.set_value("G0", 1000.0)
model.parameters.set_value("k_d_0", 1.0)
model.parameters.set_value("E_a", 40000.0)  # J/mol
model.parameters.set_value("T_ref", 300.0)

# Predict at different temperatures
sigma_300 = model.predict_flow_curve(gamma_dot, T=300.0)
sigma_350 = model.predict_flow_curve(gamma_dot, T=350.0)

Combined Usage¶

All flags compose naturally:

# Bell + FENE: shear thinning + bounded extension
model = VLBVariant(breakage="bell", stress_type="fene")
model.parameters.set_value("nu", 5.0)
model.parameters.set_value("L_max", 10.0)

# Full model with all extensions
model = VLBVariant(
    breakage="bell",
    stress_type="fene",
    temperature=True,
)

SAOS Behavior¶

In the linear regime (SAOS), the Bell breakage reduces to constant \(k_d\) because at equilibrium the chain stretch is 1. Therefore SAOS predictions are always analytical Maxwell, regardless of breakage type.

This is exact — not an approximation — because SAOS probes infinitesimally small deformations around equilibrium.

Bayesian Inference¶

VLBVariant supports the standard NLSQ + NUTS pipeline:

# NLSQ warm start
model.fit(omega, G_star, test_mode='oscillation')

# Bayesian posterior
result = model.fit_bayesian(
    omega, G_star, test_mode='oscillation',
    num_warmup=1000, num_samples=2000,
)

The model_function is fully JAX-traceable, enabling gradient-based NUTS sampling for all parameter combinations.

API Reference¶

class rheojax.models.vlb.VLBVariant(breakage='constant', stress_type='linear', temperature=False)[source]¶

Bases: VLBBase

VLB with Bell breakage, FENE-P stress, and/or temperature dependence.

This is the composable variant class for VLB models. It supports all 6 protocols via ODE integration (required when k_d depends on state).

When breakage=”constant” and stress_type=”linear”, the model matches VLBLocal exactly (regression verified).

Parameters:

breakage (Literal['constant', 'bell']) – Breakage rate function: “constant” or “bell”
stress_type (Literal['linear', 'fene']) – Stress formula: “linear” or “fene”
temperature (bool) – If True, enable Arrhenius temperature dependence

__init__(breakage='constant', stress_type='linear', temperature=False)[source]¶

Initialize VLBVariant model.

property G0: float¶: Network modulus (Pa).

property k_d_0: float¶: Unstressed dissociation rate (1/s).

property nu: float | None¶: Force sensitivity parameter (Bell only).

property L_max: float | None¶: Maximum extensibility (FENE only).

property relaxation_time: float¶: Equilibrium relaxation time t_R = 1/k_d_0 (s).

property viscosity: float¶: Zero-shear viscosity eta_0 = G0/k_d_0 (Pa·s).

model_function(X, params, test_mode=None, **kwargs)[source]¶

NumPyro/BayesianMixin model function.

Routes to appropriate prediction based on test_mode.

Parameters:

X (array-like) – Independent variable
params (array-like) – Parameter values in ParameterSet order: [G0, k_d_0, eta_s, (nu), (L_max), (E_a, T_ref)]
test_mode (str, optional) – Override stored test mode
**kwargs – Protocol-specific: gamma_dot, sigma_applied, gamma_0, omega, T

Returns:

Predicted response

Return type:

jnp.ndarray

predict_flow_curve(gamma_dot)[source]¶

Predict steady-state flow curve.

Parameters:

gamma_dot (ndarray) – Shear rate array (1/s)

Return type:

tuple[ndarray, ndarray]

Returns:

sigma (np.ndarray) – Steady-state shear stress (Pa)
eta (np.ndarray) – Apparent viscosity (Pa·s)

predict_saos(omega)[source]¶

Predict SAOS moduli (Maxwell, analytical).

In the linear regime, Bell reduces to constant k_d = k_d_0.

Parameters:

omega (ndarray) – Angular frequency array (rad/s)

Return type:

tuple[ndarray, ndarray]

Returns:

G_prime (np.ndarray) – Storage modulus G’ (Pa)
G_double_prime (np.ndarray) – Loss modulus G’’ (Pa)

predict_normal_stresses(gamma_dot)[source]¶

Predict steady-state first normal stress difference N1.

For Bell breakage, this requires ODE integration.

Parameters:: gamma_dot (ndarray) – Shear rate array (1/s)
Returns:: N1 values (Pa)
Return type:: ndarray

simulate_startup(t, gamma_dot, return_full=False)[source]¶

Simulate startup shear.

Parameters:

t (ndarray) – Time array (s)
gamma_dot (float) – Applied shear rate (1/s)
return_full (bool) – If True, return dict with stress, N1, strain

Returns:

Shear stress sigma(t), or dict with full trajectory

Return type:

ndarray | dict

simulate_relaxation(t, gamma_dot_preshear=10.0)[source]¶

Simulate stress relaxation after cessation of flow.

Parameters:

t (ndarray) – Time array (s)
gamma_dot_preshear (float) – Pre-shear rate (1/s)

Returns:

Relaxing stress sigma(t)

Return type:

ndarray

simulate_creep(t, sigma_applied)[source]¶

Simulate creep (stress-controlled).

Parameters:

t (ndarray) – Time array (s)
sigma_applied (float) – Applied stress (Pa)

Returns:

Strain gamma(t)

Return type:

ndarray

simulate_laos(t, gamma_0, omega, n_cycles=10)[source]¶

Simulate Large Amplitude Oscillatory Shear (LAOS).

Parameters:

t (ndarray | None) – Time array (if None, auto-generated from n_cycles)
gamma_0 (float) – Strain amplitude
omega (float) – Angular frequency (rad/s)
n_cycles (int) – Number of cycles (if t is None)

Returns:

‘t’, ‘strain’, ‘stress’, ‘gamma_dot’

Return type:

dict

predict_uniaxial_extension(eps_dot)[source]¶

Predict steady-state extensional stress.

For FENE-P, extensional stress is bounded (no singularity).

Parameters:: eps_dot (ndarray) – Extension rate array (1/s)
Returns:: Extensional stress sigma_E (Pa)
Return type:: ndarray

extract_laos_harmonics(result=None, n_harmonics=5)[source]¶

Extract Fourier harmonics from LAOS data.

Parameters:

result (dict | None) – LAOS result dict (uses stored _trajectory if None)
n_harmonics (int) – Number of harmonics to extract

Returns:

‘harmonics’: array of harmonic intensities ‘I3_I1’: third-to-first harmonic ratio

Return type:

dict

weissenberg_number(gamma_dot)[source]¶

Compute Weissenberg number Wi = t_R * gamma_dot.

Return type:: float

deborah_number(omega)[source]¶

Compute Deborah number De = t_R * omega.

Return type:: float

VLBVariant — Bell, FENE-P & Temperature¶

Quick Reference¶

Overview¶

Constructor Flags¶

Parameters¶

Bell Breakage Model¶

Theory¶

Usage¶

FENE-P Finite Extensibility¶

Theory¶

Usage¶

Temperature Dependence¶

Theory¶

Usage¶

Combined Usage¶

SAOS Behavior¶

Bayesian Inference¶

See Also¶

API Reference¶