---
title: 'SaddleScape V1.0: Landscape Construction'
url: https://www.emergentmind.com/topics/saddlescape-v1-0
type: topic
---

# SaddleScape V1.0: Landscape Construction

Searching arXiv for the primary paper and directly related saddle-dynamics / landscape-construction work.
**SaddleScape V1.0** is a Python software package for constructing **solution landscapes** of nonlinear systems using **High-index Saddle Dynamics (HiSD)** and related methods. In the package’s formulation, a solution landscape is a pathway map consisting of stationary points together with their interconnections, so the software is designed not merely to compute one minimum or one transition state, but to recover a hierarchical network of local minima, index-1 saddles, and higher-index saddles, together with the relations among them. It supports both gradient systems, defined by energy functions or functionals, and general non-gradient autonomous dynamical systems, and it combines saddle-dynamics formulations with matrix-free Hessian or Jacobian-vector products, multiple eigensolver backends, restart mechanisms, visualization, and export tools [2601.01081].

## 1. Concept and problem domain

SaddleScape V1.0 is organized around the idea that many nonlinear models in condensed matter physics, materials science and phase transitions, chemical reaction landscapes, protein folding and biomolecular systems, liquid crystals, Bose-Einstein condensates, biological dynamics and cell fate models, biochemical reaction networks, PDE or phase-field models, and machine learning loss landscapes are better understood through their **solution landscapes** than through isolated stationary states alone [2601.01081].

For gradient systems with twice Fréchet differentiable energy \(E(\boldsymbol{x})\), the package uses
\[
\boldsymbol{F}(\boldsymbol{x})=-\nabla E(\boldsymbol{x}), \qquad \mathbb{H}(\boldsymbol{x})=\nabla^2 E(\boldsymbol{x}).
\]
A critical point \(\hat{\boldsymbol{x}}\) satisfies
\[
\|\boldsymbol{F}(\hat{\boldsymbol{x}})\|=0.
\]
For a nondegenerate critical point, the Morse index is the number of negative eigenvalues of \(\mathbb{H}(\hat{\boldsymbol{x}})\). Minima therefore have index \(0\), transition states have index \(1\), and higher-index saddles have index \(k>1\) [2601.01081].

For non-gradient autonomous systems,
\[
\dot{\boldsymbol{x}}=\boldsymbol{F}(\boldsymbol{x}),\qquad \boldsymbol{x}\in\mathbb{R}^d,
\]
the package generalizes the same organizing principle by replacing Morse index with unstable dimension. Around an equilibrium \(\hat{\boldsymbol{x}}\), the Jacobian
\[
\mathbb{J}(\boldsymbol{x})=\nabla \boldsymbol{F}(\boldsymbol{x})
\]
determines unstable, stable, and center subspaces, and the equilibrium index is the dimension of the unstable subspace [2601.01081].

This places SaddleScape within the line of work that treats a landscape as a graph of stationary points and dynamically discovered connections rather than as a single optimization target. Earlier generalized high-index saddle dynamics formulated this viewpoint explicitly for both gradient and non-gradient systems and introduced downward and upward search procedures for graph construction [2002.10690].

## 2. High-index saddle dynamics and implemented variants

The package’s core numerical methodology is **HiSD** for gradient systems. If \(\mathcal V=\mathrm{span}\{\boldsymbol v_1,\dots,\boldsymbol v_k\}\) approximates the negative eigenspace of the Hessian at an index-\(k\) saddle, then HiSD evolves the state by ascending in \(\mathcal V\) and descending in \(\mathcal V^\perp\):
\[
\beta^{-1}\boldsymbol{\dot{x}}=\left( \mathbb{I} - 2 \sum_{i=1}^{k} \boldsymbol{v}_i \boldsymbol{v}_i^\top \right) \boldsymbol{F}(\boldsymbol{x}).
\]
The directional variables are evolved by
\[
\gamma^{-1} \boldsymbol{\dot{v}}_i = -\left( \mathbb{I} - \boldsymbol{v}_i \boldsymbol{v}_i^\top - 2 \sum_{j=1}^{i-1} \boldsymbol{v}_j \boldsymbol{v}_j^\top \right) \mathbb{H}(\boldsymbol{x}) \boldsymbol{v}_i,\quad i=1,\ldots,k.
\]
Together these define the full gradient-system HiSD dynamics implemented in SaddleScape V1.0 [2601.01081].

For non-gradient systems, the package implements **Generalized HiSD (GHiSD)**. Its state equation preserves the same reflected-flow structure,
\[
\beta^{-1}\dot{\boldsymbol{x}} = \left( \mathbb{I} - 2 \sum_{j=1}^{k} \boldsymbol{v}_j \boldsymbol{v}_j^\top \right) \boldsymbol{F}(\boldsymbol{x}),
\]
while the directional variables evolve according to
\[
\gamma^{-1}\dot{\boldsymbol{v}}_i = \left( \mathbb{I} - \boldsymbol{v}_i \boldsymbol{v}_i^\top \right) \mathbb{J}(\boldsymbol{x}) \boldsymbol{v}_i - \sum_{j=1}^{i-1} \boldsymbol{v}_j \boldsymbol{v}_j^\top \left( \mathbb{J}(\boldsymbol{x}) + \mathbb{J}^\top(\boldsymbol{x}) \right) \boldsymbol{v}_i.
\]
A simplified discrete GHiSD, equivalent to explicit Euler discretization, is also implemented through repeated Jacobian-vector updates and orthonormalization [2601.01081].

The package further includes **Accelerated HiSD (AHiSD)**. In heavy-ball form,
\[
\boldsymbol{x}^{(n+1)} = \boldsymbol{x}^{(n)} + \beta^{(n)} \left( \mathbb{I} - 2 \sum_{i=1}^{k} \boldsymbol{v}_i^{(n)} {\boldsymbol{v}_i^{(n)}^\top \right) \boldsymbol{F}(\boldsymbol{x}^{(n)}) + \alpha (\boldsymbol{x}^{(n)} - \boldsymbol{x}^{(n-1)}),
\]
and in Nesterov-type form,
\[
\boldsymbol{w}^{(n)} = \boldsymbol{x}^{(n)} + \alpha^{(n)} (\boldsymbol{x}^{(n)} - \boldsymbol{x}^{(n-1)}),
\]
followed by a reflected-gradient step from \(\boldsymbol{w}^{(n)}\). The paper gives two momentum schedules and prefers
\[
\alpha^{(n)} = \frac{n}{n+3}.
\]
In the implementation, acceleration acts on the state variable \(x\), while eigendirections are updated through an eigensolver or direct HiSD-type evolution [2601.01081].

A practical feature of V1.0 is that HiSD does not require explicit dense Hessians. When exact Hessians are unavailable, the package uses the dimer-style central-difference approximation
\[
\boldsymbol{H}(\boldsymbol{x}, \boldsymbol{v}, l) = -\frac{\boldsymbol{F}(\boldsymbol{x}+l\boldsymbol{v}) - \boldsymbol{F}(\boldsymbol{x}-l\boldsymbol{v})}{2l} \approx \mathbb{H}(\boldsymbol{x}) \boldsymbol{v},
\]
which makes the implementation matrix-free in large-dimensional settings [2601.01081].

## 3. Landscape construction strategy

A major feature of SaddleScape V1.0 is that it automates **solution-landscape construction** rather than only single-saddle search. The landscape is represented as a directed graph \(G=(V,E)\), where vertices are saddle points or equilibria with coordinates and index, and edges are hierarchical connections from higher-index to lower-index points [2601.01081].

The primary exploration mechanism is **downward search**. Starting from a known index-\(k\) saddle, the package generates a small perturbation in the full space, projects it onto the unstable subspace, scales it to size \(O(\varepsilon)\), selects \(m\) directions from the \(k\) unstable directions to form an initial subspace \(\mathcal V_m^{(0)}\), and then runs HiSD or GHiSD so that the system escapes along the discarded unstable directions and converges toward a connected index-\(m\) saddle. The implementation includes uniform or Gaussian perturbations, exploration of all \(\binom{k}{m}\) unstable-direction combinations, symmetric perturbations \(\pm \boldsymbol p\), and the simplification to plain gradient descent when \(m=0\) [2601.01081].

The package also includes **upward search**, described as a restart-based strategy for finding higher-index saddles from lower-index ones or refining an incomplete landscape. In the software this is exposed through restart interfaces rather than as a separate solver. A typical upward step perturbs the current point, augments the initial eigensubspace by combining unstable directions with selected stable directions, and then runs HiSD so that the dynamics escape along selected stable directions [2601.01081].

For global orchestration, V1.0 uses **breadth-first search (BFS)** with a **FIFO queue**. The workflow begins by attempting to find the highest-index saddle up to `MaxIndex`, then repeatedly pops saddles from the queue, generates perturbations and initial eigensubspaces for target lower indices, launches HiSD or GHiSD, checks whether newly converged saddles are novel, and either inserts them into the queue or merely records a new edge. The package explicitly addresses both the **identification problem**, namely whether a newly converged saddle is already known, and the **completeness problem**, namely how enough branches may be explored to recover a near-complete landscape [2601.01081].

This graph-oriented workflow is consistent with earlier generalized HiSD work, which defined solution landscapes as pathway maps of stationary points and their connections and used downward and upward search to build them [2002.10690].

## 4. Software architecture and interfaces

The software is modular and centered on the `Landscape` class in `SaddleScape.py`. Its main user-facing methods are concise but broad in scope.

| Component | Main items | Role |
|---|---|---|
| Top-level class | `Landscape` | Landscape construction and user workflow |
| Core solver | `HiSDSolver.py` / `Solver` | Runs HiSD, GHiSD, and variants |
| Visualization/export | `Trajectory.py`, `Connection.py`, `Save.py` | Plots trajectories and graph, exports results |

The `Landscape` class provides `Run`, `RestartFromPoint`, `RestartFromSaddle`, `DrawTrajectory`, `DrawConnection`, and `Save`. Parameter validation is handled by `LandscapeCheckParam.py` and `HiSDSolverCheckParam.py`, which raise errors for invalid inputs and assign default values for missing ones [2601.01081].

The package supports multiple input modes. Through `AnaCal.py`, users may provide direct callable functions for energy and gradient, symbolic energy functions compiled to numerical callables, symbolic energy expressions differentiated automatically, user-specified symbolic gradients compiled numerically, or numerical gradients via central differences if only a numerical energy is provided. The principal functions listed are `EnergyFunctionAnalysis`, `EnergyFunctionCalculate`, `AutoDerivative`, `ExactGradAnalysis`, `AutoGrad`, and `AutoGradNum` [2601.01081].

Hessian and Jacobian handling is implemented in `HessianMatrix.py`, with functions including `SingleHessianVectorProduct`, `BatchHessianVectorProduct`, `Hessian_Analysis_withIfsym`, `Hessian_Analysis`, `Hessian_exact`, and `Hessian`. The implementation strongly prefers operator-based Hessian use over explicit dense Hessian formation in higher dimensions [2601.01081].

The eigensolver layer in `EigMethod.py` includes `lobpcg` and `lobpcg_exacthessian` for gradient systems with symmetric Hessians, `power_nonGrad` and `power_nonGrad_exacthessian` for non-gradient systems, and Euler-discretization methods for both system types. The default choice is **LOBPCG** for gradient systems and the **power method** for non-gradient systems. Reproducibility-related utilities include `CheckIndexk`, `FindIndex`, `GiveEigenvector`, `CanonicalizeEigens`, and `CanonicalizeMatrix`, with canonicalization intended to improve cross-device reproducibility when eigenspaces have multiplicities [2601.01081].

Postprocessing supports 1D and 2D plotting, projected visualization for high-dimensional trajectories, network visualization using `networkx`, and export to JSON, MATLAB `.mat`, and Pickle `.pkl`. The repository and introductory website are publicly identified in the package paper [2601.01081].

## 5. Usage workflow and demonstrated applications

The package paper describes a typical workflow in eight steps. One first defines either a gradient system through `EnergyFunction` and optionally `Grad`, or a non-gradient system through the vector field under the package’s sign convention. One then selects whether the system is gradient or non-gradient, chooses the solver mode, sets `MaxIndex` and a target `SaddleIndex`, configures numerical parameters such as `TimeStep`, `MaxIter`, `Tolerance`, dimer length, eigensolver, Barzilai-Borwein stepping, acceleration type, perturbation number and radius, and eigen-combination policy, then constructs a `Landscape` object and calls `Run`. Convergence is checked by gradient norm, the saddle index is verified, degeneracy warnings may be issued, and the resulting landscape may be visualized or exported. Incomplete landscapes can be refined with `RestartFromPoint` or `RestartFromSaddle` [2601.01081].

Four examples anchor the package description. The **butterfly function**
\[
E(x,y)=x^{4}-1.5x^{2}y^{2}+y^{4}-2y^{3}+y^{2}+x^{2}y-2x^{2}
\]
serves as a basic two-dimensional demonstration, where the package finds the index-2 maximum, index-1 saddles, and minima, and plots both search trajectories and the resulting landscape. The **Müller-Brown potential**
\[
E_{MB}(x,y)=\sum_{i=1}^{4}A_{i}\exp [a_{i}(x-\bar{x}_{i})^{2}+b_{i}(x-\bar{x}_{i})(y-\bar{y}_{i})+c_{i}(y-\bar{y}_{i})^{2}]
\]
is used to show that one initial search may give an incomplete graph and that restart-based refinement can recover a complete landscape. The **cubic function**
\[
E(x)=\sum_{j=1}^{n}j(x_{j}^{2}-1)^{2}
\]
illustrates a highly structured symmetric landscape; for \(n=3\), it has \(27\) saddle points at \((a,b,c)\) with \(a,b,c\in\{-1,0,1\}\). Finally, a **phase-field model**
\[
E(\phi) = \int_{\Omega} \left( \frac{\kappa}{2} |\nabla \phi|^2 + \frac{1}{4} (1 - \phi^2)^2 \right) dx
\]
demonstrates application to a discretized functional on a \(64\times64\) grid with periodic boundary conditions, including a custom equivalence predicate to identify translationally equivalent saddles [2601.01081].

The phase-field example is especially representative of SaddleScape’s intended use on discretized PDE energies. Earlier generalized HiSD work had already shown that discretized phase-field models admit solution-landscape construction through downward and upward searches, including both gradient and non-gradient variants [2002.10690].

## 6. Position within the saddle-dynamics literature

SaddleScape V1.0 is best understood as an implementation platform for the **HiSD family** rather than as a generic umbrella for all meanings of “saddle.” Its scope is distinct from convex-concave saddle modeling and from local transition-state searches based on single index-1 methods. For example, the spring pair method is a Hessian-free, gradient-only method designed to locate one index-1 saddle connected to a known minimum and is explicitly positioned as a single-saddle local search method rather than a full path-optimization or landscape-construction framework [2407.04373].

Within the HiSD line itself, V1.0 corresponds to a first integrated software release. Subsequent work addresses limitations that the package paper leaves open. A semi-implicit discretization of HiSD analyzes larger stable time steps and faster convergence than explicit schemes while preserving controlled approximation of the continuous saddle dynamics [2310.04643]. Improved HiSD introduces a crossover from gradient flow to traditional HiSD and provides stable and nonlocal convergence from outside the region of attraction to the saddle point, together with a Morse-theoretic argument that any two saddle points could be connected by a sequence of trajectories of iHiSD, which partly answers the completeness issue of the solution landscape [2502.03694]. Preconditioned HiSD reformulates the continuous dynamics in a Riemannian metric induced by an SPD preconditioner and proves a discrete linear convergence rate governed by a preconditioned condition number \(\kappa_M\), reducing iteration complexity from \(O(\kappa\log(1/\varepsilon))\) to \(O(\kappa_M\log(1/\varepsilon))\) on ill-conditioned problems [2603.25390].

These later developments clarify what V1.0 does and does not yet contain. The package paper states several limitations directly. Its core theory focuses mainly on nondegenerate critical points and hyperbolic equilibria; degenerate saddles can occur, and the package warns about them rather than fully resolving them. Explicit full Hessian formation is discouraged in high dimensions. Landscape completeness is not guaranteed automatically in difficult systems, and restart or parameter tuning may be needed. Output may vary across devices because eigenvectors in multiple eigenspaces are nonunique, although canonicalization helps. The package is not described as parallel or GPU-accelerated, and constrained HiSD, data-driven variants, and true functional or infinite-dimensional solvers are not part of V1.0 [2601.01081].

In that sense, SaddleScape V1.0 occupies a specific place in the literature: it operationalizes high-index saddle dynamics, generalized high-index saddle dynamics, and accelerated HiSD in a single research-oriented Python package, with explicit support for graph-based solution-landscape construction. Its distinctive contribution is not a new saddle-search theorem alone, but a software realization of index-controlled exploration in which critical points, their indices, and their interconnections become first-class computational objects [2601.01081].

Source: https://www.emergentmind.com/topics/saddlescape-v1-0