bSTAB: an open-source software for computing the basin stability of multi-stable dynamical systems

Abstract

The pervasiveness of multi-stability in nonlinear dynamical systems calls for novel concepts of stability and a consistent quantification of long-term behavior. The basin stability is a global stability metric that builds on estimating the basin of attraction volumes by Monte Carlo sampling. The computation involves extensive numerical time integrations, attractor characterization, and clustering of trajectories. We introduce bSTAB, an open-source software project that aims at enabling researchers to efficiently compute the basin stability of their dynamical systems with minimal efforts and in a highly automated manner. The source code, available at https://github.com/TUHH-DYN/bSTAB/, is available for the programming language Matlab featuring parallelization for distributed computing, automated sensitivity and bifurcation analysis as well as plotting functionalities. We illustrate the versatility and robustness of bSTAB for four canonical dynamical systems from several fields of nonlinear dynamics featuring periodic and chaotic dynamics, complicated multi-stability, non-smooth dynamics, and fractal basins of attraction. The bSTAB projects aims at fostering interdisciplinary scientific collaborations in the field of nonlinear dynamics and is driven by the interaction and contribution of the community to the software package.

1 Introduction

Stability analysis plays a central role in nonlinear dynamics research, whether for structural dynamics, fluid flows, chemical reactions, or others [1]. Linear and local stability concepts are standard methods for the characterization of point attractors and (quasi-) periodic orbits. However, these stability concepts are limited to small perturbations when assessing the long-term system behavior and stability against perturbations. In a multi-stability situation, i.e. when multiple stable solutions co-exist, global metrics are required for studying the stability of a state against any type of perturbation, whether small or non-small. The basin stability proposed by Menck et al. [2, 3] is a global stability concept based on the estimated volume of the basins of attraction in the system’s phase space, which can overcome some limitations of classical local stability concepts. Practically, the basin stability indicates the probability of the system to arrive on one of the multiple solutions when perturbing the current state of the system. This stability concept is of relevance especially for designing practical application systems which are always subject to uncertainty of initial conditions or instantaneous perturbations. The concept of basin stability has led to a better understanding of some complex dynamical systems. For example, power grids were studied with a special interest in finding those network nodes that are critical for the network stability [4]. Albeit being a rather simplistic theoretical concept, the practical computation of the basin stability involves extensive Monte Carlo simulations and several technical challenges for researchers who want to study the basin stability of their dynamical systems.

As the major contribution of the work at hand, bSTAB aims at equipping researchers with a readily implemented tool to compute the basin stability of a dynamical system with minimal effort and high efficiency. The bSTAB toolbox aims at making the basin stability analysis easier to perform, hence helping this global stability metric make its way to a state-of-the-art analysis tool for nonlinear dynamical systems. bSTAB is designed to be model-agnostic, i.e. the user is required to have only basic knowledge about the system at hand, typical ODE formulations can be re-used, and only very limited coding skills are needed. Hence, this toolbox can be integrated into existing analysis routines without much effort. The toolbox is licensed under the GNU General Public License v3.0 and is freely available through https://github.com/TUHH-DYN/bSTAB/, which aims at providing easy access and high visibility. The code is under active development, and the community can add functionalities or report issues within the git framework. This project shall foster communication and collaborations across scientific disciplines, and at the same time grow the functionalities of bSTAB further.

Multi-stable dynamical systems [5] in the form of coupled oscillators [6] or complex networks [7] are omnipresent in many scientific disciplines, such as in biology [8], physics [9], chemistry [10, 11], psychology [12], finance [13], ecology [14], climatology [15], medicine [16], and many more [17, 18]. Depending on the initial condition, multi-stable systems exhibit different time-asymptotic behavior. Recently, multi-stability has obtained attention in mechanical systems which are not necessarily cyclic, nor of network form: fluttering airfoils [19], few-degree-of-freedom friction oscillators [20,21,22], friction oscillator chains [23], and (hyper-chaotic) self-excited oscillators [24] amongst others. Experimental observations of multi-stable mechanical systems range from bi-stable automotive friction brake vibrations [25] , bi-stable responses of helicopter blades [26], windtunnel airfoil tests [27, 28], to small cyclic mechanical structures with gap-induced nonlinear vibration localization [29].

Classically, bifurcation diagrams are computed for nonlinear dynamical systems to study the character of different solutions, and their qualitative change under system parameter variations. Subcritical bifurcation points, also denoted as tipping points are of special interest, as they form the connection of unstable and stable solutions in bi-stable system configurations. Bifurcation diagrams are helpful for studying questions related to which dynamics are possible? Even though the computation of unstable solutions, representing the boundaries of the basins of attraction in phase space, is possible, bifurcation analysis can only barely answer questions related to which dynamics are the most probable?. Owing to the possibly intermingled or fractal geometries of the basins of attraction, a simple basin size estimation can become very challenging even for few-degree-of-freedom systems [22]. Lyapunov functions [30, 31] can assess the stability against large perturbations, but they are difficult to find, especially for high-dimensional systems. Many open-source software projects exist for computing bifurcation diagram, such as MatCont [32] and NLvib [33], but yet no basin stability toolbox exists. This work aims at addressing this white spot for scientific communities working on nonlinear dynamical systems.

The basin stability concept relies on measuring the volumes of the basins of attraction $\mathcal {B}$ in the $D-$ dimensional state space. The basin stability value $\mathcal {S}_{\mathcal {B}}\left( A\right)$ of the attractor A is given by [2, 3, 7]

$$\begin{aligned} \mathcal {S}_{\mathcal {B}}\left( A\right) = \int \kappa _{\mathcal {B}}\left( \mathbf {y}\right) \rho \left( \mathbf {y}\right) \mathrm {d} \mathbf {y}, \quad \mathbf {y} \in \mathbb {R}^{D}, \quad \mathcal {S}_{\mathcal {B}} \in \left[ 0, 1\right] \end{aligned}$$

(1)

where $\kappa \left( \mathbf {y} \right)$ is an indicator function

$$\begin{aligned} \kappa \left( \mathbf {y} \right) = {\left\{ \begin{array}{ll} 1,&{} \text {if } \mathbf {y} \in \mathcal {B}\left( A \right) \\ 0, &{} \text {otherwise} \end{array}\right. } \end{aligned}$$

(2)

stating whether a trajectory converged to the attractor A, and thus whether $\mathbf {y}$ belongs to the basin $\mathcal {B}\left( A\right)$. $\rho$ is a density distribution of states that the system may be perturbed to with $\int _{\mathbb {R}} \rho \left( \mathbf {y}\right) \mathrm {d} \mathbf {y} = 1$. Estimates for the basin stability are obtained through Monte Carlo sampling from $\rho$, resulting in the absolute standard error of the estimate

$$\begin{aligned} e_{\mathrm {abs}} = \sqrt{\mathcal {S}_{\mathcal {B}}\left( A\right) \left( 1-\mathcal {S}_{\mathcal {B}}\left( A\right) \right) /N} \end{aligned}$$

(3)

for the N-times repeated Bernoulli experiment, i.e. the square root of the variance. Hence, the choice of N is independent of the state space dimension, which is especially helpful for high-dimensional systems. The relative error of the estimate

$$\begin{aligned} e_{\mathrm {rel}} = 1/\sqrt{N \mathcal {S}_{\mathcal {B}}\left( A\right) } \end{aligned}$$

(4)

becomes relevant for small basin stability values, potentially requiring to increase N into the range $N \sim 1/\mathcal {S}_{\mathcal {B}}\left( A\right)$ [3]. Each state is numerically integrated, and the fraction of trajectories approaching the respective attractor is calculated to yield the basin stability estimate. In the following, we use $\mathcal {S}_{\mathcal {B}}$ to indicate the estimate of the actual basin stability value for reasons of readability.

This work is structured as follows: the basin stability concept is re-visited briefly in Sect. 2 with a focus on computational challenges for practitioners. Next, the structure of bSTAB is introduced in Sect. 3 along with typical workflows for studying the global stability of multi-stable dynamical systems. Sect. 4 illustrates the use of the toolbox for four canonical time-continuous dynamical systems.

2 Methods

This section re-visits the concept of basin stability from the more technical viewpoint, i.e. discussing how Eqs. (1), and (2) can be translated into efficient programs with flexible choice of parameters. First, the general nomenclature is introduced.

Nonlinear dynamical systems

$$\begin{aligned} \dot{\mathbf {y}} \!=\! \mathbf {f}\left( \mathbf {y}, \mathbf {p} \right) , \quad \mathbf {y}\left( t\right) \!=\! \left[ y_1\left( t\right) , \dots , y_D\left( t\right) \right] ^{\top } \in \mathbb {R}^{D} \end{aligned}$$

(5)

are considered in their D-dimensional phase space. Model parameters are collected in $\mathbf {p} = \left[ p_1, \dots , p_j\right] ^{\top }$, and may be varied for parameter studies such as bifurcation diagrams. The time evolution of the states is referred to as the trajectory $\mathbf {y}\left( t \right)$. Typically, time marching solvers, such as Runge–Kutta schemes, are employed to solve the initial value problem that is associated with finding the trajectory $\mathbf {y}\left( t\right)$ for some initial condition $\mathbf {y}_0=\mathbf {y}\left( t=0\right)$ and the time t. Given that the trajectory converges to either a fixed point, to a (quasi)-periodic orbit, or to a chaotic attractor, the system settles to some steady-state solution, denoted as $\bar{\mathbf {y}}$, after an initial transient phase. The basin of attraction $\mathcal {B}\left( \bar{\mathbf {y}}\right)$ for the steady-state solution $\bar{\mathbf {y}}$ denotes the subset of the phase space from which all initial conditions converge towards $\bar{\mathbf {y}}$ as $t \rightarrow \infty$. If the system has only one stable solution, the corresponding basin of attraction fills the complete phase space. However, in a multi-stability scenario, the phase space can be subdivided into k different basins of attraction if the system has k stable steady-state solutions $\bar{\mathbf {y}}_{1, \dots , k}$. The boundaries of the basins, i.e. the separatrices, are given by the unstable solutions of the system. The concept of basin stability is a probabilistic approach to estimating the volumes $V_{1, \dots , k}$ of the basins of attractions by sampling a finite number N of states from the distribution $\rho$ and classifying the corresponding steady-state trajectories into one class of the k stable solutions. The fraction of each basin’s volume $V\left( \mathcal {B}_i \right)$ in the phase space covered by $\rho$ is denoted as the basin stability value $\mathcal {S}_{\mathcal {B}} \left( \bar{\mathbf {y}}_i\right)$. Methodically, four main steps are involved in the basin stability computation, which are introduced in the following paragraphs. Particularly, a consistent formalization is required for the implementation of a model-agnostic computing toolbox that can run highly automated analysis with minimal user interaction.

2.1 Selection of the region of interest and Monte Carlo sampling

Even though the state space has an infinite size, typically only a small portion of this space represents a set of admissible states and potential perturbations for a dynamical system. Therefore, the distribution $\rho$ is typically confined to a hypercube in $\mathbb {R}^{D}$, which is referred to as region of interest $\mathcal {Q}\left( \mathbf {y} \right) \subset \mathbb {R}^{D}$. $\mathcal {Q}$ should cover the set of possible initial conditions, but also the set of states that would result from perturbing a steady-state solution $\bar{\mathbf {y}} + \epsilon$. Hence, the selection of $\mathcal {Q}$ is specific to the dynamical system at hand, and relies on the expertise of the domain expert studying this particular system. Naturally, the selected region of interest crucially affects the final absolute basin stability values. One may interpret the a-priori selection of the region of interest as a weak point of the basin stability concept. However, one may on the other hand also argue that for classical local stability metrics the actual size of small, i.e. admissible, perturbations is unknown, too. In bSTAB, the user specifies the minimum and maximum state values per state space dimension to set $\mathcal {Q}$. N initial conditions are drawn from the region of interest $\mathcal {Q}$ following the distribution $\rho$. For the distribution, a bounded uniform distribution at random is the classical choice [2] that guarantees basin stability values to be proportional to the true basins’ volumes for $N \rightarrow \infty$. However, in certain situations different sampling strategies may be considered. For example, if a distribution of initial conditions or admissible perturbations is known from previous studies or experiments, they can be supplied through a custom definition of $\rho$. In the latter case, the basin stability values will no longer be an estimate for the basins’ volumes. Instead, the basin stability values will indicate probabilities for observing a specific steady-state solution $\bar{\mathbf {y}}$ under the distribution $\rho$. bSTAB comes with the following D-dimensional distributions $\rho$ readily implemented: bounded uniform random distribution, bounded multivariate Gaussian distribution, and multivariate uniformly spaced grid sampling. Furthermore, bSTAB allows the user to sample only from a subset of the D dimensions, i.e. exclude some dimensions from the sampling, and thereby create a hypercube $\mathcal {Q}$ that has less dimensions than the state space D. Figure 1 illustrates a schematic for the specification of the region of interest, as well as different distributions $\rho$.

Fig. 1

Schematic for the definition of the region of interest $\mathcal {Q}$ as a subset of the state space (here: $\mathbb {R}^2$) for a system that is $k=3$ multi-stable in (a). The panel on the right hand side shows $N=500$ samples drawn from different distributions $\rho$: (b) uniform random distribution, (c) multivariate Gaussian distribution and (d) uniformly spaced multivariate grid within the boundaries $\left[ a, b\right] \times \left[ a, b\right]$

2.2 Numerical time integration

For each state $\mathbf {y}_0$ sampled from $\mathcal {Q}$, the steady-state is obtained by solving the initial value problem by numerical time integration. Particularly, the steady-state $\bar{\mathbf {y}}$ is reached at time $t^{*}$, i.e. after this time the dynamics are qualitatively constant with respect to either statistical properties, spectral properties, geometric [34] and dynamical invariant measures [35,36,37], or other descriptors of the nonlinear dynamics [38]. The integration time span must be chosen large enough such that also slow or even chaotic transients [39] have died out. The numerical time marching scheme, error tolerance settings, the time step length, and other parameters may affect the time-asymptotic behavior, especially for chaotic systems with exponential divergence of nearby starting trajectories. As investigated by Schulz et al. [40], numerical approximation and rounding errors may infer with the basin stability estimation when trajectories start, or come, close to a basin boundary, particularly for fractal boundaries. bSTAB provides functionalities to perform sensitivity analysis studies of the basin stability values against parameters of the numerical integration scheme. Classical Runge–Kutta schemes from Matlab’s ode suite are provided: ode45 for fast computations, ode23t for vanishing numerical damping, and ode113 for numerically stiff systems.

2.3 Classification of asymptotic trajectories

The third step involves turning the indicator function $\kappa _{\mathcal {B}}\left( \mathbf {y}\right)$ in Eq. (2) into a data-driven feature extraction and clustering task. Steady-state trajectories $\mathbf {y}\left( t > t^* \right)$ are characterized by descriptive features $\mathbf {X}$ in order to assign a label L of membership to one of the k solutions. For this purpose, the feature extraction function $\phi$

$$\begin{aligned} \mathbf {X} = \phi \left( \mathbf {y}\left( t > t^* \right) \right) , \quad \mathbf {X} = \left[ X_1, \dots , X_m\right] \end{aligned}$$

(6)

converts dynamic data (trajectories $\mathbf {y}(t)$) into static data (descriptive features $\mathbf {X}$), and can be considered the most crucial ingredient to a fully automated basin stability computation. The formulation of the operator $\phi$ directly depends on the complexity and the diversity of the dynamical behavior of the system: if only a fixed-point solution $\bar{\mathbf {y}}_1$ needs to be distinguished from a periodic steady-state $\bar{\mathbf {y}}_2$, a trivial amplitude threshold can serve as discriminative feature X. In situations involving multiple solutions with higher degrees of similarity, the feature extraction function $\phi$ may involve advanced signal processing techniques (linear time series analysis, nonlinear time series analysis [36], recurrence plot quantification analysis [37], generalized feature extraction [38]) in order to come up with a set of m characteristic features $X_{1, \dots , m}$ that can be used for the classification of different trajectories. The user must specify a feature extraction function in bSTAB taking trajectory data $\mathbf {y}(t)$ as input and returning a feature vector $\mathbf {X}$.

Depending on the a-priori knowledge about the multi-stable dynamics, the labeling takes the form of a supervised or unsupervised clustering procedure $\mathcal {C}$. Assuming complete knowledge about all k solutions (supervised setting), template features $\bar{\mathbf {X}}_{1, \dots , k}$ can be derived per a-priori known template solution $\bar{\mathbf {y}}_{1, \dots , k}$. Then, a label to a new trajectory $\mathbf {y}\left( t\right)$ is selected by comparing the new feature vector against the template vectors and assigning the class label L according to the minimal distance

$$\begin{aligned} \mathcal {C}: \mathbf {X} \mapsto L, \quad \mathrm {min}\left( \left| \mathbf {X}, \bar{\mathbf {X}}_i \right| \right) \mapsto L, \quad i=1, \dots , k \quad . \end{aligned}$$

(7)

A k-nearest neighbor classification algorithm (kNN) with a single nearest neighbor is provided with bSTAB, creating Voronoi partitions in the m-dimensional feature space upon which the labels are assigned, see Fig. 2a. If only incomplete knowledge about possible solutions is available, the unsupervised setting aims at finding clusters in the feature space. Particularly, not all solutions are required to be known, hence leaving the number k unknown, and making template feature definitions impossible. The unsupervised clustering algorithm DBSCAN (Density-Based Spatial Clustering of Applications with Noise) [41] is employed to derive optimally separated clusters for the N feature vectors $\mathbf {X}$ in the $m-$dimensional feature space, thereby finding k by the number of identified clusters. The unsupervised setting enables users of the toolbox to blindly put a less-known dynamical system at test, and let bSTAB find out which and how many multi-stable solutions can arise from states in $\mathcal {Q}$.

Fig. 2

Clustering methods for feature vectors to clusters, i.e. assigning trajectories to a basin of attraction. (a) single nearest neighbor supervised clustering making use of template vectors for defining the Voronoi partitions of the feature space. (b) unsupervised clustering using density-reachable and density-connected points within an $\epsilon$ sphere in the DBSCAN method

2.4 Computation of the basin stability estimates

Having classified the N trajectories into the k classes of steady-states $\bar{\mathbf {y}}_{1, \dots , k}$, the number of class members $N_{1, \dots , k}$ is available. Here, $N_i$ denotes the number of initial conditions $\mathbf {y}_{0}$ that converge to the ith steady-state solution $\bar{\mathbf {y}}_{i}$ with $i = 1, \dots , k$ and $\sum _{i=1}^{k}N_i = N$. The resulting estimate for the basin stability value, i.e. the estimate for each basin’s volume’s $V\left( \mathcal {B}_i\right)$ share in $\mathcal {Q}$, is given by

$$\begin{aligned} \mathcal {S}\left( \mathcal {B}_{i}\right) = \frac{N_{i}}{N}, \quad \sum \mathcal {S}\left( \mathcal {B}_{i} \right) = 1, \quad i = 1, \dots , k \quad . \end{aligned}$$

(8)

Naturally, the basin stability values add up to unity if all N trajectories were able to be classified belonging to one of the k solutions.

3 Implementation aspects of bSTAB

This section illustrates the workflow and the readily available analysis routines in bSTAB. Details on the actual implementation, further options and annotated test cases are shown in the user manual (the latest version is accessible through https://github.com/TUHH-DYN/bSTAB/) for bSTAB. Generally, the toolbox covers three major analysis modes, which cover most of the requirements for the analysis of nonlinear dynamical systems across various scientific disciplines:

mode 1::

computation of the basin stability values $\mathcal {S}_{\mathcal {B}}$ at a fixed set of model parameters $\mathbf {p}$ using the routine compute_bs.

mode 2::

computation of the sensitivity of the basin stability values against workflow hyperparameters. Hyperparameters are denoted as settings that are independent of the dynamical system at hand, e.g. number of sampling points and numerical tolerances. Sensitivity studies are performed using the routine compute_bs_ap, which allows to specify a wide range of adaptive parameters.

mode 3::

computation of the basin stability values along the variation of a model parameter p in analogy to conventional bifurcation analysis using the routine compute_bs_ap.

Mode 1 implements the core methodologies of the toolbox as described in the previous paragraphs, while modes 2 and 3 implement automatic looping through the parameter variations and calling mode 1 iteratively. The pseudo-code displayed in Algorithm 1 shows the implementation of mode 1 in bSTAB.

To illustrate a typical basin stability computation using mode 1, the necessary commands are briefly discussed. More details can be found in the user manual.

$$\begin{aligned} \begin{aligned}&\mathtt{currentCase = 'my\_case'; } \\&\mathtt{[props] = init\_bSTAB(currentCase); } \\&\mathtt{[props] = setup\_system(props); } \\&\mathtt{[res\_tab, res\_detail, props] = compute\_bs(props);} \\&\mathtt{plot\_bs\_bargraph(props, res\_tab);} \end{aligned} \end{aligned}$$

Each case study (first line) must be given a unique name in bSTAB for creating respective sub-directories which store the computation results. init_bSTAB initializes the bSTAB toolbox and setup_system is the case definition function. The case definition setup_system serves as anchor for running cases, hence all model parameters and hyperparameters need to be specified here by the user. compute_bs returns the basin stability values per solution in res_tab in the format of a table. plot_bs_bargraph creates a bar graph showing the basin stability values for each solution. Readers who are interested in setting up a small test case and experimenting with the toolbox are invited to consider the user manual for tutorials and more details about further functionalities. Overall, the setup of bSTAB is at the one hand highly flexible, and on the other hand easy to use: after setting up the case, the computation and visualization of the results comes down to 5 lines of code. All case studies presented in the upcoming Sect. 4 are covered in detail in the manual, and the corresponding codes are provided within the toolbox source files.

Parallelization across multiple computing cores or compute nodes is enabled through parallelized loops (parfor) in Matlab. Particularly, looping over all initial conditions for computing the time integrations and extracting features can easily be parallelized, see lines $3-5$ in Algorithm 1. The parallelization of the Monte Carlo simulations enables (approximately) linear scaling of the reduction in compute time for increasing number of compute cores. Figure 3 displays parallel speedups for one of the case studies shown in Sect. 4, namely the bi-stable chaotic Lorenz system at $\sigma =0.12$, $r=0$, $b=-0.6$. The analysis was performed using $N=5\cdot 10^5$ samples and an extra-long time integration span of $10^4$. Even though absolute computing times are affected by multiple factors related to the hardware and software resources, qualitative trends can be read from the analysis. Compute times are compared to the duration of a not-parallelized run on one worker, which in absolute numbers took 0.2938 seconds per sample. The study shows that the speedup linearly scales in a 2 : 1 ratio, such that using 8 workers reduces the computation time by the factor 4 compared to using a single worker. The scaling property makes the toolbox especially valuable for running larger case studies on high-performance machines making use of massive parallelization.

Fig. 3

Computational speedup obtained through parallelization of the Monte Carlo simulations across multiple CPUs on a desktop computer (Xeon(R) W-2255 10$\times$3.7 GHz, 64 GB RAM) running Matlab R2020a on Linux Ubuntu 20.04.1 LTS

4 Canonical case studies using bSTAB

A range of four canonical dynamical systems is studied to illustrate the novel insights provided by basin stability analysis and to highlight the main functionalities in bSTAB. From the vast number of multi-stable dynamical systems [18], we select (1) a bi-stable (fixed point and periodic solution) damped driven pendulum, (2) a multi-stable (five periodic solutions) configuration of the Duffing oscillator, (3) a bi-stable (chaotic and chaotic) variant of the Lorenz system, and (4) a bi-stable (fixed point and periodic solution) non-smooth self-excited friction oscillator. The Appendix 5 lists all parameter settings and user-defined options for those case studies, such that readers can reproduce and verify our results. The different modes of the toolbox, namely basin stability computation, sensitivity analysis and model parameter bifurcation studies, are presented.

Fig. 4

The basin stability of the damped driven pendulum system for $\alpha =0.1$, $K=1.0$ and $T=0.5$ with a stable fixed point FP at $\bar{\mathbf {y}}_1 = \left[ \psi , 0 \right] ^{\top }$ and a limit cycle LC at $y_2=T/\alpha$. Both steady-state solutions are depicted in (a) starting from $\mathbf {y}_0=\left[ \epsilon , \epsilon \right] ^{\top }$ (FP) and $\mathbf {y}_0=\left[ \phi -\pi +\epsilon , \epsilon \right] ^{\top }$ (LC) with $\epsilon =0.1$. The fixed point’s basin of attraction $\mathcal {B}\left( \mathrm {FP}\right)$ is depicted in (b), where white areas belong to $\mathcal {B}\left( \mathrm {LC}\right)$. Using $n=10^4$ sampling points, the basin stability values $\mathcal {S}_{\mathcal {B}}\left( \bar{\mathbf {y}}_1\right) = 0.15$, $\mathcal {S}_{\mathcal {B}}\left( \bar{\mathbf {y}}_3\right) = 0.85$ are derived using bSTAB

4.1 Bi-stable damped driven pendulum

Following the original work by Menck et al. [2], first the basin stability of the damped driven pendulum (length l, damping coefficient $\alpha$, angular acceleration T, gravitational acceleration g, $K=g/l$) is investigated

$$\begin{aligned} \begin{aligned} \dot{y}_1&= y_2\\ \dot{y}_2&= -\alpha y_1 + T - K \sin \left( y_1 \right) \end{aligned} \end{aligned}$$

(9)

as a minimalistic system that exhibits bi-stability. Following a linear stability analysis for $0 \le T \le K$, the system has two fixed points at $\bar{\mathbf {y}}_1=\left[ \psi , 0 \right] ^{\top }$ and $\bar{\mathbf {y}}_2=\left[ \pi -\psi , 0 \right] ^{\top }$ with $\psi =\mathrm {arcsin}\left( T/K\right) \in \left[ 0, \pi /2\right]$. For $0<T<K$ the first point is a stable fixed point, while the second point is an unstable saddle point. For $T>K$, there exists a stable limit cycle solution $\bar{\mathbf {y}}_3$ for which $\dot{y}_1$ oscillates around $T / \alpha$. For certain parameter settings, the limit cycle exists also for $T<K$, giving rise to bi-stability for the competing solutions $\bar{\mathbf {y}}_1$ and $\bar{\mathbf {y}}_3$ for $0.13 \le T \le K=1$.

The original study [2] is replicated and displayed in Fig. 4. $N=10^4$ states are sampled uniformly at random from the region of interest $\mathcal {Q}\left( y_1, y_2\right) :\left[ \psi -\pi , \psi + \pi \right] \times \left[ -10, 10 \right]$. For this choice of $\mathcal {Q}$, the basin stability value of the fixed point is $\mathcal {S}_{\mathcal {B}}\left( \bar{\mathbf {y}}_1\right) = 0.15$, and for the limit cycle solution $\mathcal {S}_{\mathcal {B}}\left( \bar{\mathbf {y}}_3\right) = 0.85$. The global stability picture obtained through this analysis hence adds insight into the dynamical system: Both solutions are stable (as indicated by linear stability analysis), but the periodic response is more than five times more likely to occur than the fixed point solution at the given parameter combination and the chosen distribution $\rho$, which is the additional piece of information that complements the local stability statements. Even though the system dynamics may seem trivial, manually or analytically estimating the basins’ volumes is in fact non-trivial, see Fig. 4b. The basin of attraction of the fixed point is composed of many thin islands in the selected region of interest. The model-agnostic character of bSTAB helps the user to estimate those volumes in a completely automated fashion and enables effortless variations of the region of interest. All bSTAB parameters are given in Appendix A.

In a second study, the torque T is varied to study the local stability and the basin stability of both solutions along the parameter variation, hence making use of mode 3 in bSTAB. The bi-stable regime begins at $T=0.13$, after which the stable fixed point FP and the limit cycle LC co-exist, see Fig. 5. The basin stability values are computed for a grid of torque values, and the linear stability analysis for the fixed point is computed along. The Lyapunov exponent $\lambda$ associated with the fixed point $\bar{\mathbf {y}}_1$ is constant throughout the complete parameter regime up to $T=0.99999$, thereby indicating the stability of the fixed point, but not a transition of the qualitative dynamics picture of the system. On the other hand, the basin stability depicts how the global stability role of the fixed point solution vanishes for increasing driving torques, until eventually the fixed point solution disappears through a fold bifurcation at $T=K=1$. The authors in [2] argue that the basin stability analysis can yield a better early warning sign for the critical tipping point of this system than local stability concept would allow.

Fig. 5

Comparison of local and global stability metrics: (a) Lyapunov exponent of the fixed point $\bar{\mathbf {y}}_1$ along the driving torque T and (b) the basin stability $\mathcal {S}_{\mathcal {B}}$ of the fixed point and the limit cycle using $N=10^3$ sampling points per torque value

For all pendulum studies the feature extraction task in Eq. 6 was required to formulate features X that would separate a fixed point solution from a limit cycle solution in the steady-state regime $\tilde{y} = y\left( t>t^*\right)$ irrespective of absolute amplitude values. For this purpose, the deviation of the maximum rotational velocity $y_2\left( t\right)$ about the average rotational velocity was considered

$$\begin{aligned} \mathbf {X}= & {} \left[ X_1, X_2\right] ^{\top }\nonumber \\= & {} {\left\{ \begin{array}{ll} \left[ 1, 0\right] ^{\top },&{} \text {if } \Delta \le 0.01\\ \left[ 0, 1\right] ^{\top }, &{} \text {otherwise} \end{array}\right. }, \quad \Delta = \left| \text {max}\left( \tilde{y}_2 \right) - \text {mean}\left( \tilde{y}_2\right) \right| \nonumber \\ \end{aligned}$$

(10)

using a one-hot encoding with respect to a threshold value to generate the feature vector $\mathbf {X}$. Full knowledge about all solutions of the system is available a-priori, hence the supervised classification using the kNN method was chosen for this system.

4.2 Multi-stable Duffing oscillator: five co-existing limit cycles

The Duffing oscillator

$$\begin{aligned} \begin{aligned} \dot{y}_1&= y_2 \\ \dot{y}_2&= -\delta y_2 -k_3 y_1^3 + F\, \mathrm {cos} \left( t \right) \end{aligned} \end{aligned}$$

(11)

is studied in a particular parameter setting ($\delta = 0.08$, $k_3=1$, $F=0.2$) that allows this small system to exhibit complicated multi-stability [42]: five periodic solutions co-exist for this configuration. There are two period$-1$ limit cycles $\bar{\mathbf {y}}_1$, $\bar{\mathbf {y}}_2$, two period$-2$ limit cycles $\bar{\mathbf {y}}_3$, $\bar{\mathbf {y}}_4$ and one period$-3$ limit cycle $\bar{\mathbf {y}}_5$. As all of them are linearly stable, the shape and the volumes of the basins of attraction are of particular interest, but at the same time very challenging to derive analytically. The share of each basin in the state space $\mathcal {Q}$ will dictate the probability of the system approaching either of the five solution in the time-asymptotic limit. The region of interest $\mathcal {Q}\left( y_1, y_2\right) : \left[ -1.0, 1.0\right] \times \left[ -0.5, 1.0\right]$ is chosen, such that states on all solutions are covered. Moreover, $\mathcal {Q}$ includes situations when the system vibrates on the large-amplitude cycle $\bar{\mathbf {y}}_2$ and experiences some non-small perturbation in positive displacement and velocity direction. All basin stability analysis parameters are given in Appendix B.

Fig. 6

a displacement trajectories $y_1\left( t\right)$ for the five stable limit cycle solutions $\bar{\mathbf {y}}_{1, \dots , 5}$ of the Duffing oscillator in Eq. (11) and b the corresponding state space representation of the steady-state solutions. c $N=5000$ samples from the region of interest labeled by their long-term behavior and d the feature space spanned by the maximum displacement ($X_1$) and the displacement standard deviation ($X_2$) being used for clustering the trajectories

Figure 6a,b depicts the five limit cycles in state space as well as the trajectories in time domain, where the qualitative and quantitative differences of the solutions become obvious. The high-energy solution $\bar{\mathbf {y}}_2$ may be particularly challenging for the fatigue life time of a realistic system behaving Duffing-like, while some of the lower-amplitude solutions with a broader vibration spectrum may be favorable for energy harvesting devices. Figure 6c depicts the states sampled from the region of interest colored by their class label. The basin boundaries show a complicated shape with many intertwining tongues. The resulting basin stability values are $\mathcal {S}_{\mathcal {B}}\left( \bar{\mathbf {y}}_{1, \dots , 5} \right) = \left[ 0.1934, 0.4922, 0.0284, 0.0248, 0.2612 \right]$: The large-amplitude period$-1$ cycle $\bar{\mathbf {y}}_2$ has by far the largest basin stability, and the two period$-2$ cycles have an almost vanishing probability of less than $3\%$ in the chosen region of interest. $\bar{\mathbf {y}}_5$ is the second most-likely and $\bar{\mathbf {y}}_1$ is the third most-likely solution of the system in the given configuration. Those results may be used to tune the dynamical system or adapt control strategies for arriving at the desired dynamical behavior. Again, this piece of information is not possible to extract from conventional linear stability analysis, and would not be easy to obtain from bifurcation diagrams or other conventional methods to measure the basins of attraction. Figure 6d depicts the feature space $\mathbf {X}$ which is used by the kNN clustering algorithm to assign class labels to the feature vectors $\mathbf {X}_i$. For deriving features from the trajectories, the maximum displacement $X_1=\mathrm {max}\left( \tilde{y}_1 \left( t\right) \right)$ and the displacement’s standard deviation $X_2=\mathrm {std}\left( \tilde{y}_1 \left( t\right) \right)$ in the steady-state regime $\tilde{y}\left( t\right) = y\left( 900 \le t \le 1000\right)$ are considered. Even though these features are rather simplistic, they turn out to be uniquely separable in the feature space with only minimal inner-class variance. In this case, the supervised clustering mode was used, hence initial conditions for each of the five solutions were supplied to the toolbox, which allowed to compute template feature vectors per class (indicated by cross markers in Fig. 6d).

The bSTAB toolbox allows the user to arrive at these results without additional effort besides setting up the case and running the computation using mode 1 of the software package. All graphical output shown in Fig. 6 is created automatically, and all settings and results are stored in a local folder sub-directory for the current study. Changing the region of interest, the number of samples or other parameters only requires changing the respective values in the case definition file and re-running the analysis. This design of the toolbox aims at enabling the user to quickly perform several analysis runs, and re-visit the results later on without having to consider version control or extensive logging of case specifications.

4.3 Multi-stable Lorenz system: periodic and chaotic states

Li and Sprott [43] study the famous Lorenz system [44]

$$\begin{aligned} \begin{aligned} \dot{x}&= \sigma \left( y-x\right) \\ \dot{y}&= rx-xz-y \\ \dot{z}&= xy-bz \end{aligned} \end{aligned}$$

(12)

in a parameter setting which exhibits particularly interesting multi-stable dynamics: for $r=0$, $b=-0.6$ and $\sigma =0.12$ the system has two stable co-existing chaotic attractors. Even if the resulting model may no longer represent the dynamics of convection rolls or chemical reactions [45], it is an interesting case study also for the basin stability analysis. Figure 7 shows the bifurcation behavior of the system under a variation of the model parameter $\sigma$. As this parameter is decreased, two co-existing limit cycles undergo a period-doubling route to chaos until they eventually are destroyed in a boundary crisis after $\sigma =0.12$. Chaos is born at $\sigma \approx 0.1225$. The two co-existing attractors are symmetric and the chaotic sets were entitled a broken butterfly by Li and Sprott [43]. Even though the attractors approach each other very closely at $x=0$, they remain separated throughout the range of $\sigma$.

Fig. 7

Period-doubling route to chaos for decreasing values of $\sigma$ of the Lorenz system in Eq. (12) at $r=0$, $b=-0.6$. The multi-stable solutions are initialized at $\mathbf {y}_0\left[ -0.8, 3.0, 0.0\right] ^{\top }$ (red trajectories) and at $\mathbf {y}_0\left[ 0.8, -3.0, 0.0\right] ^{\top }$ (blue trajectories)

Fig. 8

Slice of the basins of attraction taken at $z=0$ using $N=5\cdot 10^4$ sampling points for $r=0$, $b=-0.6$. White areas in the state space relate to states leading into unbounded orbits

Instead of deriving the basin stability at a fixed parameter set, the basin stability of both attractors is studied along a variation of $\sigma$ using mode 3 (variation of a model parameter) in bSTAB. The specification of all parameters is given in Appendix C. A region of interest $\mathcal {Q}\left( x, y, z\right) : \left[ -10, 10 \right] \times \left[ -20, 20 \right] \times \left[ 0 \right]$ is selected that excludes the z coordinate from the sampling. For a range of $\sigma$ values the basin stability is computed for $N=5\cdot 10^4$ samples from a uniform random distribution each. The basin stability analogue to the bifurcation diagram is depicted in Fig. 8. The analysis shows that more than $80\%$ of the trajectories lead to unbounded orbits. The basin stability of both attractors are very similar owing to the symmetrical structure about the z axis of the basins of attraction shown in the lower panel of Fig. 8. For the four parameter values investigated in detail, the basins of attraction exhibit an intricate and fractal shape [43], which per se is an interesting observation: For $\sigma >0.01225$ regular dynamics arise in a system that has fractal basin boundaries. Moreover, while the dynamics change rather strongly along $\sigma$ in terms of amplitude and their qualitative characteristics, the basins of attraction remain rather unchanged. As a direct result of this observation, the basin stability values of both attractors are $\mathcal {S}_{\mathcal {B}}\approx 0.09$ throughout the parameter range studied here.

Fractal basin boundaries [46] raise questions with regards to the applicability of the Monte Carlo sampling-based stability concept. Schulz et al. [40] investigate the limitations of the basin stability concept for systems with “‘fractal, riddled, or intermingled basin boundaries”’. The authors find that “the numerical basin stability estimation is still meaningful for fractal boundaries”’ if large N are chosen. Utilizing bSTAB for hyperparameter studies (mode 2) using the compute_bs_ap routine, Fig. 9a displays the basin stability values of the two coexisting chaotic attractors at $\sigma =0.12$ as a function of the number of sampling point ranging up to $N=20,000$. The basin stability values for this set of parameters saturates quickly at $N \approx 10^3$ with only small fluctuations for smaller values of N. The relative tolerance setting of the numerical integration scheme was studied in a second hyperparameter study. The standard fourth-order Runge–Kutta ode45 integrator is used with an absolute error tolerance of $10^{-6}$. The relative tolerance value is changed in the range of $10^{-3}$ (default setting) to $10^{-8}$ using $N=10^{4}$ points and a bounded uniform random distribution $\rho$ on $\mathcal {Q}$. Figure 9b shows that only minor differences can be observed between the default and very strict tolerance settings. The difference between a tolerance of $10^{-3}$ and a tolerance of $10^{-8}$ is $\Delta \mathcal {S}_{\mathcal {B}} = 0.0066$ for the first attractor and $\Delta \mathcal {S}_{\mathcal {B}} = 0.0004$ for the second attractor, which is a small deviation considering a basin stability value $\mathcal {S}_{\mathcal {B}} = 0.0923$ ($\mathcal {S}_{\mathcal {B}} = 0.0822$) for the first (second) attractor. Larger numbers of samples would even reduce the effect of the numerical integration scheme on the basin stability estimates.

Fig. 9

The basin stability values for the Lorenz system in Eq. 12 at $\sigma =0.12$, $r=0$, $b=-0.6$ as a function of hyperparameters: a variation of the number of sampled N and b variation of the relative error tolerance of the numerical integration scheme

4.4 Non-smooth frictional oscillator

A single-mass linear oscillator $M\ddot{x} +C\dot{x} +Kx = F_{\mathrm {fric}}$ displayed in Fig. 10a with a non-smooth frictional contact is studied following previous works [20, 22]. The friction force is described by velocity-dependent weakening friction slope $\mu \left( v_{\mathrm {rel}}\right)$ shown in Fig. 10b according to

$$\begin{aligned} \begin{aligned}&v_{\mathrm {rel}} = \dot{x}-v_{\mathrm {d}} \\ v_{\mathrm {rel}} \ne 0: \quad&F_{\mathrm {fric}}=-F_{\mathrm {N}} \mu \left( v_{\mathrm {rel}}\right) \mathrm {sign}\left( v_{\mathrm {rel}}\right) \\ v_{\mathrm {rel}} = 0: \quad&\left| F_{\mathrm {fric}}\right| < \mu _{\mathrm {st}} F_{\mathrm {N}} \\&\mu \left( v_{\mathrm {rel}}\right) = \mu _{\mathrm {d}} + \left( \mu _{\mathrm {st}}-\mu _{\mathrm {d}} \right) \mathrm {exp} \left( - \frac{\left| v_{\mathrm {rel}}\right| }{v_0} \right) \end{aligned} \end{aligned}$$

(13)

giving rise to friction-induced self-excited stick-slip vibrations, see Fig. 10c. $\mu _{\mathrm {st}} = \mu \left( 0 \right)$ denotes the static friction coefficient, $\mu _{\mathrm {d}} = \mu \left( v_{\mathrm {rel}} \rightarrow \infty \right)$ denotes the dynamic friction coefficient in the asymptotic limit, $v_{\mathrm {d}}$ is the driving velocity of the conveyor belt, $v_0$ is the reference velocity, and the contact is loaded by the normal force $F_{\mathrm {N}}$. The non-dimensional form $\left( \tilde{\cdot } \right)$ of the system

$$\begin{aligned} \tilde{\ddot{x}} +2 \xi \tilde{\dot{x}} + \tilde{x} = \tilde{F}_{\mathrm {fric}} \end{aligned}$$

(14)

is obtained by $\omega _n=\sqrt{K/M}$, $\xi =C/\left( 2 \sqrt{KM}\right)$, $x_0=F_{\mathrm {N}}/K$, $\tau = \omega _n t$ and $\mathrm {d}/\mathrm {d}t=\omega _n \mathrm {d}/\mathrm {d}\tau$. The parameters are chose $\mu _{\mathrm {d}}=0.5$, $\mu _{\mathrm {st}}=1.0$, $\xi =0.005$, $F_{\mathrm {N}}=1$ and $\tilde{v}_0=0.5$.

Fig. 10

The single-mass frictional oscillator in (a) with a falling friction law shown in (b) that exhibits bi-stable behavior. c displays two trajectories for $\tilde{v}_{\mathrm {d}}=1.5$ starting at $\mathbf {y}_0=\left[ 2.0, 2.0\right] ^{\top }$ (upper panel) resulting in a stick-slip limit cycle and at $\mathbf {y}_0=\left[ 1.0, 1.0\right] ^{\top }$ (lower panel) resulting in a stable steady sliding fixed point

Fig. 11

Bi-stability along the belt velocity parameter: a bifurcation diagram and b Lyapunov exponent of the fixed point solution. Stable (unstable) solutions are depicted by solid (dashed) lines. c displays the basin stability of both solutions for $\mathcal {Q}\left( x, \dot{x}\right) : \left[ -2, 2 \right] \times \left[ -2, 2 \right]$ using $N=5 \cdot 10^3$ sampling points from a uniform random distribution

Fig. 12

Variation of the density distribution: uniform random (left column (a) and (d)), multivariate Gaussian (center column (b) and (e)), uniformly spaced grid (right column (c) and (f)) for $\mathcal {Q}\left( x, \dot{x}\right) : \left[ -2, 2 \right] \times \left[ 0, 2 \right]$ using $N=5 \cdot 10^3$ sampling points for the friction oscillator at $\tilde{v}_{\mathrm {d}}=1.5$. Red colors relate to the steady sliding fixed point FP and blue colors relate to the stick-slip limit cycle LC shown by the solid line

The oscillator exhibits bi-stability for $1.11 \le \tilde{v}_{\mathrm {d}} \le 1.84$: small initial displacements and velocities die out quickly as the trajectories converge to the stable fixed point of steady sliding. Larger initial states push the system into a stable stick-slip limit cycle which is self-excited through the negative friction slope Eq. 13. For low velocities $\tilde{v}_{\mathrm {d}}<1.11$ only a stable limit cycle exists, while for larger velocities $\tilde{v}_{\mathrm {d}}>1.84$ the steady sliding state is globally stable. The correponding bifurcation diagram is shown in Fig. 11a along with the eigenvalue’s real part in (b). The real part approaches the positive half plane as $\tilde{v}_{\mathrm {d}}$ is decreased and hence may indicate a qualitative change of the dynamics in the sense of an early warning sign (in contrast to the pendulum case discussed in Sect. 4.1). Naturally, the co-existence of a stable limit cycle in the range of negative real parts cannot be obtained from the linear stability analysis of the fixed point. The basin stability analysis displayed in Fig. 11c represents a quantitative measure for both stable solutions as a function of the sliding velocity. For the given choice of the region of interest, the basin stability scales linearly with the velocity up to $\tilde{v}_{\mathrm {d}} \approx 1.83$: for $1.11 \le \tilde{v}_{\mathrm {d}} \le 1.6$ the stick-slip cycles are more likely to occur, and for $1.6 \le \tilde{v}_{\mathrm {d}} \le 1.84$ the steady sliding state dominates the time-asymptotic behavior under the selected distribution of states. All case parameters are given in Appendix D. This study shall illustrate how the basin stability analysis complements classical approaches to studying stability and bifurcation behavior of nonlinear dynamical systems.

Figure 12 depicts the usage of different distributions $\rho$ in bSTAB and the resulting differences in the basin stability values. For a different choice of $\mathcal {Q}\left( x, \dot{x}\right) : \left[ -2, 2 \right] \times \left[ 0, 2 \right]$, a uniform random distribution (a), a multivariate Gaussian (b) distribution and sampling from a uniformly spaced grid (c) are studied. The sampling points nicely indicate the unstable periodic orbit that separates both basins of attraction within the area encircled by the stick-slip trajectory.

The maximum difference of basin stability values amounts to 0.097 comparing the Gaussian distribution to the grid sampling. This study illustrates how the user can specify custom sampling strategies and distributions, and thus adapt the analysis to an individual system for which a specific distribution of admissible perturbations may be known. The structure of bSTAB requires changing only a single line (props.roi.samplingPDF = ’uniform’) in the case definition for running those different analysis, and hence enables quick interaction of the user with the results, and reduces efforts related to changing programming codes.

5 Conclusion

This work introduces an open-source computing toolbox for estimating the basin stability of continuous dynamical systems exhibiting multi-stability. Complementing conventional local stability analysis, the basin stability represents a global stability metric for estimating the share of each basin of attraction in the system’s state space. Thereby, basin stability translates into probabilities of arriving on one of the competing multi-stable solutions under a distribution of admissible initial states or instantaneous perturbations. Albeit the simplicity of the theoretical concept, practical issues and pitfalls can arise for researchers willing to implement a basin stability analysis of their dynamical systems of interest. Thanks to a plethora of software packages existing for stability and bifurcation analysis of nonlinear dynamical systems, these methods have made their way into the state-of-the-art toolbox in the scientific community. However, an easy-to use toolbox for computing the basin stability has not been proposed yet, potentially hindering the penetration of this rather new stability concept into the toolbox of nonlinear dynamics researchers.

The bSTAB project aims at filling this void. The proposed implementations constitute a highly formalized structure for computing the basin stability with as minimal interaction required by the user as possible. Following a model-agnostic approach, common implementations of dynamical systems can be re-used, such that the basin stability analysis can easily be incorporated into existing analysis procedures. Efficient Monte Carlo simulations are enabled through parallelization strategies for multi-core and high-performance computers. Consistent quantification of multi-stability with error estimates is presented for four canonical nonlinear multi-stable dynamical systems featuring regular, chaotic and non-smooth dynamics, complicated and fractal basin boundary shapes as well as bifurcations along parameter variations.

Table 1 Setup definition of the pendulum case study

Table 2 Setup definition of the Duffing oscillator case study

Table 3 Setup definition of the Lorenz system case study

The concept of open-source software is chosen to enable barrier-free access to the implementation, but also foster interdisciplinary cooperation among nonlinear dynamics researchers. Active code development by the community will help to grow functionalities further, to cover even more efficient implementations and programming languages, and to extent the capabilities of the toolbox to maps and network systems.

Appendices

A Definition of the pendulum case

The settings for the driven damped pendulum presented in Sect. 4.1 are given in Table 1 following the implementation in setup_pendulum.m provided with bSTAB.

Table 4 Setup definition of the friction oscillator case study

B Definition of the Duffing oscillator case

The case definition details for the Duffing oscillator case discussed in Sect. 4.2 is given in Table 2 and in setup_duffing.m provided with bSTAB.

C Definition of the Lorenz system case

Section 4.3 shows a particular configuration of the Lorenz system and various analysis steps performed in bSTAB. Table 3 gives the case definition details employed for all studies if not stated differently.

D Definition of the friction oscillator case

Table 4 gives the case definition details employed for the friction oscillator case study.