LVEEnvelope¶

Overview¶

The rheojax.transforms.LVEEnvelope transform computes the linear viscoelastic (LVE) startup stress envelope \(\sigma_{\text{LVE}}^+(t)\) from a Prony series representation of the relaxation modulus. This analytical prediction provides the theoretical stress growth response assuming linear viscoelasticity.

Key Capabilities:

Startup stress prediction: \(\sigma_{\text{LVE}}^+(t)\) for any shear rate
Nonlinearity detection: Compare with experimental startup data to identify strain hardening or softening
JIT-compiled: Fully JAX-accelerated evaluation for fast sweeps over multiple rates
Flexible input: Prony parameters via constructor or from RheoData metadata

The LVE envelope is a cornerstone of nonlinear rheology characterization. In a startup experiment, the material’s stress growth follows the LVE envelope at early times but deviates at a characteristic strain—the Hencky strain at onset of nonlinearity—revealing the material’s nonlinear response.

Mathematical Theory¶

Startup Stress in Linear Viscoelasticity¶

For a material subjected to constant shear rate \(\dot{\gamma}_0\) starting at \(t = 0\), the Boltzmann superposition integral gives the transient stress:

\[\sigma^+(t) = \dot{\gamma}_0 \int_0^t G(s) \, ds\]

Substituting the Prony series \(G(t) = G_e + \sum_i G_i \exp(-t/\tau_i)\):

\[\sigma_{\text{LVE}}^+(t) = \dot{\gamma}_0 \left[ G_e \, t + \sum_{i=1}^{N} G_i \tau_i \left(1 - \exp(-t/\tau_i)\right) \right]\]

Limiting behaviors:

Short time (\(t \ll \tau_{\min}\)): \(\sigma \approx \dot{\gamma}_0 \left(G_e + \sum G_i\right) t\) (elastic response, slope = glassy modulus × rate)
Long time (\(t \gg \tau_{\max}\)): \(\sigma \to \dot{\gamma}_0 \left(G_e \, t + \sum G_i \tau_i\right)\) (steady state for viscoelastic solids, or constant \(\eta_0 \dot{\gamma}_0\) for liquids)

Steady-state viscosity (for liquids, \(G_e = 0\)):

\[\eta_0 = \lim_{t \to \infty} \frac{\sigma_{\text{LVE}}^+(t)}{\dot{\gamma}_0} = \sum_{i=1}^{N} G_i \tau_i\]

Nonlinearity Assessment¶

Comparing \(\sigma_{\text{exp}}^+(t)\) with \(\sigma_{\text{LVE}}^+(t)\):

\(\sigma_{\text{exp}} > \sigma_{\text{LVE}}\): Strain hardening (common in branched polymers, associating networks)
\(\sigma_{\text{exp}} < \sigma_{\text{LVE}}\): Strain softening (common in linear polymers at high rates, shear thinning)
\(\sigma_{\text{exp}} = \sigma_{\text{LVE}}\): Linear regime (low rates, small strains)

Damping function extraction:

\[h(\gamma) = \frac{\sigma^+(t)}{\sigma_{\text{LVE}}^+(t)} \bigg|_{\gamma = \dot{\gamma}_0 t}\]

Parameters¶

LVEEnvelope Parameters¶
Parameter	Type	Default	Description
`shear_rate`	float	`1.0`	Applied shear rate \(\dot{\gamma}_0\) (s^-1).
`G_i`	ndarray \| None	`None`	Prony mode strengths (Pa). Read from `data.metadata` if `None`.
`tau_i`	ndarray \| None	`None`	Prony relaxation times (s). Read from `data.metadata` if `None`.
`G_e`	float	`0.0`	Equilibrium modulus (Pa). Set to 0 for viscoelastic liquids.
`t_out`	ndarray \| None	`None`	Output time array. Auto-generated if `None` (200 log-spaced points from 0.01 to \(10 \tau_{\max}\)).

Parameter Selection Guidelines¶

Shear rate:

Match the experimental startup rate for direct comparison
Sweep rates to generate a family of LVE envelopes for rate-dependent analysis

Prony parameters:

Obtain from PronyConversion transform
Or from ../models/gmm/generalized_maxwell model fitting
Or supply directly from literature values

Input / Output Specifications¶

Input: Optional RheoData. If G_i/tau_i were set at construction, data can be None. If data is provided, its x values are used as the time array, and G_i/tau_i can be read from data.metadata.
Output: RheoData with x = time (s), y = \(\sigma_{\text{LVE}}^+(t)\) (Pa). Metadata includes shear_rate, n_modes, and source_transform.

Usage¶

Direct Parameter Input¶

from rheojax.transforms import LVEEnvelope
import numpy as np

# Two-mode polymer melt
G_i = np.array([5e3, 2e3])       # Mode strengths (Pa)
tau_i = np.array([0.1, 10.0])    # Relaxation times (s)

# Compute LVE envelope at γ̇ = 1 s⁻¹
lve = LVEEnvelope(shear_rate=1.0, G_i=G_i, tau_i=tau_i)
envelope_data, info = lve.transform()

t = envelope_data.x
sigma_lve = envelope_data.y

# Steady-state viscosity: η₀ = Σ Gᵢτᵢ
eta_0 = np.sum(G_i * tau_i)
print(f"η₀ = {eta_0:.0f} Pa·s")

Rate Sweep for Nonlinear Comparison¶

import matplotlib.pyplot as plt
import numpy as np
from rheojax.transforms import LVEEnvelope

G_i = np.array([1e4, 3e3, 500])
tau_i = np.array([0.01, 1.0, 100.0])

rates = [0.01, 0.1, 1.0, 10.0]
t = np.logspace(-3, 3, 500)

fig, ax = plt.subplots()
for rate in rates:
    lve = LVEEnvelope(shear_rate=rate, G_i=G_i, tau_i=tau_i, t_out=t)
    data, _ = lve.transform()
    ax.loglog(data.x, data.y, label=fr'$\dot{{\gamma}} = {rate}$ s$^{{-1}}$')

ax.set_xlabel('Time (s)')
ax.set_ylabel(r'$\sigma_{\mathrm{LVE}}^+$ (Pa)')
ax.legend()
ax.set_title('LVE Envelope Family')

From Prony Conversion Output¶

from rheojax.transforms import PronyConversion, LVEEnvelope

# Step 1: Fit Prony series
prony = PronyConversion(n_modes=10, direction="time_to_freq")
_, info = prony.transform(relaxation_data)
prony_result = info["prony_result"]

# Step 2: LVE envelope using fitted parameters
lve = LVEEnvelope(
    shear_rate=0.5,
    G_i=prony_result.G_i,
    tau_i=prony_result.tau_i,
    G_e=prony_result.G_e,
)
envelope_data, _ = lve.transform()

From Data Metadata¶

from rheojax.transforms import LVEEnvelope
from rheojax.core.data import RheoData
import numpy as np

# Data with Prony parameters in metadata
t = np.logspace(-2, 2, 100)
data = RheoData(
    x=t, y=np.zeros_like(t),
    metadata={'G_i': [5000, 2000], 'tau_i': [0.1, 10.0], 'G_e': 100.0}
)

lve = LVEEnvelope(shear_rate=1.0)
envelope_data, info = lve.transform(data)

result = info["lve_result"]
print(f"Modes: {len(result.G_i)}, Rate: {result.shear_rate} s⁻¹")

Output Structure¶

LVEEnvelopeResult Attributes¶
Attribute	Type	Description
`t`	ndarray	Time array (s)
`sigma_lve`	ndarray	Stress envelope \(\sigma_{\text{LVE}}^+(t)\) (Pa)
`G_i`	ndarray	Prony mode strengths used (Pa)
`tau_i`	ndarray	Prony relaxation times used (s)
`shear_rate`	float	Applied shear rate (s^-1)

API References¶

Module: rheojax.transforms
Class: rheojax.transforms.LVEEnvelope

References¶

Ferry, J.D. (1980). Viscoelastic Properties of Polymers, 3rd ed. Wiley. Chapter 4: Stress growth in startup of steady shear.
Dealy, J.M. & Larson, R.G. (2006). Structure and Rheology of Molten Polymers: From Structure to Flow Behavior and Back Again. Hanser.
Wagner, M.H. (1976). “Analysis of time-dependent non-linear stress-growth data for shear and elongational flow of a low-density branched polyethylene melt.” Rheol. Acta, 15, 136–142. DOI: 10.1007/BF01517505
Osaki, K., Inoue, T., & Isomura, T. (2000). “Stress overshoot of polymer solutions at high rates of shear.” J. Polym. Sci. Part B: Polym. Phys., 38, 1917–1925. DOI: 10.1002/1099-0488(20000715)38:14<1917::AID-POLB100>3.0.CO;2-6