zoomy_core.analysis.hyperbolicity module

zoomy_core.analysis.hyperbolicity module#

Sample-based hyperbolicity test.

Given a linearised SystemModel (or pencil matrices already in hand), evaluate the generalised eigenvalues at a grid / random sample of base states and check the imaginary parts. Reports the fraction of samples that are hyperbolic (all eigenvalues real to within tolerance) and a summary of any non-hyperbolic regions.

zoomy_core.analysis.hyperbolicity.is_hyperbolic_at(M_x, M_t, sample, *, tol=1e-09, drop_infinite=True)#

Evaluate (M_x, M_t) at sample and check eigenvalues.

Returns (hyperbolic, eigenvalues). hyperbolic is True iff every finite eigenvalue has |imag| < tol.

Parameters:

  • M_x (MutableDenseMatrix) –

  • M_t (MutableDenseMatrix) –

  • sample (Dict) –

  • tol (float) –

  • drop_infinite (bool) –

Return type:

Tuple[bool, ndarray]

class zoomy_core.analysis.hyperbolicity.HyperbolicitySample(sample: 'Dict[Any, float]', eigenvalues: 'np.ndarray', hyperbolic: 'bool')#

Bases: object

Parameters:

  • sample (Dict[Any, float]) –

  • eigenvalues (ndarray) –

  • hyperbolic (bool) –

sample: Dict[Any, float]#
eigenvalues: ndarray#
hyperbolic: bool#
class zoomy_core.analysis.hyperbolicity.HyperbolicityReport(samples: 'List[HyperbolicitySample]', fraction_hyperbolic: 'float', nonhyperbolic_samples: 'List[HyperbolicitySample]' = <factory>, notes: 'List[str]' = <factory>)#

Bases: object

Parameters:
samples: List[HyperbolicitySample]#
fraction_hyperbolic: float#
nonhyperbolic_samples: List[HyperbolicitySample]#
notes: List[str]#
summary()#
Return type:

str

zoomy_core.analysis.hyperbolicity.sample_hyperbolicity(M_x, M_t, parameter_ranges, *, n_samples=1000, rng=None, tol=1e-09, drop_infinite=True, constraint_filter=None, max_attempts=10)#

Random-uniform sample over a hyper-rectangle of parameters.

Parameters:

  • M_x (MutableDenseMatrix) – the pencil matrices (sympy).

  • M_t (MutableDenseMatrix) – the pencil matrices (sympy).

  • parameter_ranges (Dict[Any, Sequence]) – dict {sympy_symbol: (lo, hi)} for the variables you want to sample. Symbols not in this dict must already be substituted-out in the pencil (e.g. fixed at chosen values).

  • n_samples (int) – number of accepted samples to draw.

  • rng (Optional[Generator]) – optional np.random.Generator.

  • tol (float) – imaginary-part threshold for “real”.

  • drop_infinite (bool) – drop infinite generalised eigenvalues (typical for systems with constraints).

  • constraint_filter (Optional[Callable[[Dict], bool]]) – optional callable sample_dict → bool. A sample is rejected (and another drawn) if this returns False — useful for excluding e.g. h ≤ 0.

  • max_attempts (int) – per accepted sample, how many draws before giving up.

Return type:

HyperbolicityReport

Returns HyperbolicityReport.