SaddleScape V1.0: Landscape Construction

• SaddleScape V1.0 is a Python software package designed to generate hierarchical solution landscapes of nonlinear systems through high-index saddle and generalized saddle dynamics.
• It integrates methods like HiSD, GHiSD, and AHiSD to compute various stationary points—including minima, index-1 saddles, and higher-index saddles—without needing explicit dense Hessians.
• The package automates landscape construction using downward and upward search strategies, enabling visualization and export of complex networked stationary points across diverse scientific applications.

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 (Liu et al., 3 Jan 2026).

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 (Liu et al., 3 Jan 2026).

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$ (Liu et al., 3 Jan 2026).

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

$$\boldsymbol{F}(\boldsymbol{x})=-\nabla E(\boldsymbol{x}), \qquad \mathbb{H}(\boldsymbol{x})=\nabla^2 E(\boldsymbol{x}).$$0

determines unstable, stable, and center subspaces, and the equilibrium index is the dimension of the unstable subspace (Liu et al., 3 Jan 2026).

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 (Yin et al., 2020).

2. High-index saddle dynamics and implemented variants

The package’s core numerical methodology is HiSD for gradient systems. If $$\boldsymbol{F}(\boldsymbol{x})=-\nabla E(\boldsymbol{x}), \qquad \mathbb{H}(\boldsymbol{x})=\nabla^2 E(\boldsymbol{x}).$$1 approximates the negative eigenspace of the Hessian at an index-$$\boldsymbol{F}(\boldsymbol{x})=-\nabla E(\boldsymbol{x}), \qquad \mathbb{H}(\boldsymbol{x})=\nabla^2 E(\boldsymbol{x}).$$2 saddle, then HiSD evolves the state by ascending in $$\boldsymbol{F}(\boldsymbol{x})=-\nabla E(\boldsymbol{x}), \qquad \mathbb{H}(\boldsymbol{x})=\nabla^2 E(\boldsymbol{x}).$$3 and descending in $$\boldsymbol{F}(\boldsymbol{x})=-\nabla E(\boldsymbol{x}), \qquad \mathbb{H}(\boldsymbol{x})=\nabla^2 E(\boldsymbol{x}).$$4: $$\boldsymbol{F}(\boldsymbol{x})=-\nabla E(\boldsymbol{x}), \qquad \mathbb{H}(\boldsymbol{x})=\nabla^2 E(\boldsymbol{x}).$$5 The directional variables are evolved by

$$\boldsymbol{F}(\boldsymbol{x})=-\nabla E(\boldsymbol{x}), \qquad \mathbb{H}(\boldsymbol{x})=\nabla^2 E(\boldsymbol{x}).$$6

Together these define the full gradient-system HiSD dynamics implemented in SaddleScape V1.0 (Liu et al., 3 Jan 2026).

For non-gradient systems, the package implements Generalized HiSD (GHiSD). Its state equation preserves the same reflected-flow structure,

$$\boldsymbol{F}(\boldsymbol{x})=-\nabla E(\boldsymbol{x}), \qquad \mathbb{H}(\boldsymbol{x})=\nabla^2 E(\boldsymbol{x}).$$7

while the directional variables evolve according to

$$\boldsymbol{F}(\boldsymbol{x})=-\nabla E(\boldsymbol{x}), \qquad \mathbb{H}(\boldsymbol{x})=\nabla^2 E(\boldsymbol{x}).$$8

A simplified discrete GHiSD, equivalent to explicit Euler discretization, is also implemented through repeated Jacobian-vector updates and orthonormalization (Liu et al., 3 Jan 2026).

The package further includes Accelerated HiSD (AHiSD). In heavy-ball form,

$$\boldsymbol{F}(\boldsymbol{x})=-\nabla E(\boldsymbol{x}), \qquad \mathbb{H}(\boldsymbol{x})=\nabla^2 E(\boldsymbol{x}).$$9

and in Nesterov-type form,

$\hat{\boldsymbol{x}}$0

followed by a reflected-gradient step from $\hat{\boldsymbol{x}}$1. The paper gives two momentum schedules and prefers

$\hat{\boldsymbol{x}}$2

In the implementation, acceleration acts on the state variable $\hat{\boldsymbol{x}}$3, while eigendirections are updated through an eigensolver or direct HiSD-type evolution (Liu et al., 3 Jan 2026).

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

$\hat{\boldsymbol{x}}$4

which makes the implementation matrix-free in large-dimensional settings (Liu et al., 3 Jan 2026).

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 $\hat{\boldsymbol{x}}$5, where vertices are saddle points or equilibria with coordinates and index, and edges are hierarchical connections from higher-index to lower-index points (Liu et al., 3 Jan 2026).

The primary exploration mechanism is downward search. Starting from a known index-$\hat{\boldsymbol{x}}$6 saddle, the package generates a small perturbation in the full space, projects it onto the unstable subspace, scales it to size $\hat{\boldsymbol{x}}$7, selects $\hat{\boldsymbol{x}}$8 directions from the $\hat{\boldsymbol{x}}$9 unstable directions to form an initial subspace $\|\boldsymbol{F}(\hat{\boldsymbol{x}})\|=0.$0, and then runs HiSD or GHiSD so that the system escapes along the discarded unstable directions and converges toward a connected index-$\|\boldsymbol{F}(\hat{\boldsymbol{x}})\|=0.$1 saddle. The implementation includes uniform or Gaussian perturbations, exploration of all $\|\boldsymbol{F}(\hat{\boldsymbol{x}})\|=0.$2 unstable-direction combinations, symmetric perturbations $\|\boldsymbol{F}(\hat{\boldsymbol{x}})\|=0.$3, and the simplification to plain gradient descent when $\|\boldsymbol{F}(\hat{\boldsymbol{x}})\|=0.$4 (Liu et al., 3 Jan 2026).

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 (Liu et al., 3 Jan 2026).

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 (Liu et al., 3 Jan 2026).

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 (Yin et al., 2020).

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 (Liu et al., 3 Jan 2026).

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 (Liu et al., 3 Jan 2026).

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 (Liu et al., 3 Jan 2026).

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 (Liu et al., 3 Jan 2026).

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 (Liu et al., 3 Jan 2026).

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 (Liu et al., 3 Jan 2026).

Four examples anchor the package description. The butterfly function

$\|\boldsymbol{F}(\hat{\boldsymbol{x}})\|=0.$5

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

$\|\boldsymbol{F}(\hat{\boldsymbol{x}})\|=0.$6

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

$\|\boldsymbol{F}(\hat{\boldsymbol{x}})\|=0.$7

illustrates a highly structured symmetric landscape; for $\|\boldsymbol{F}(\hat{\boldsymbol{x}})\|=0.$8, it has $\|\boldsymbol{F}(\hat{\boldsymbol{x}})\|=0.$9 saddle points at $\mathbb{H}(\hat{\boldsymbol{x}})$0 with $\mathbb{H}(\hat{\boldsymbol{x}})$1. Finally, a phase-field model

$\mathbb{H}(\hat{\boldsymbol{x}})$2

demonstrates application to a discretized functional on a $\mathbb{H}(\hat{\boldsymbol{x}})$3 grid with periodic boundary conditions, including a custom equivalence predicate to identify translationally equivalent saddles (Liu et al., 3 Jan 2026).

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 (Yin et al., 2020).

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 (Cui et al., 2024).

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 (Luo et al., 2023). 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 (Su et al., 6 Feb 2025). 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 $\mathbb{H}(\hat{\boldsymbol{x}})$4, reducing iteration complexity from $\mathbb{H}(\hat{\boldsymbol{x}})$5 to $\mathbb{H}(\hat{\boldsymbol{x}})$6 on ill-conditioned problems (Huang et al., 26 Mar 2026).

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 (Liu et al., 3 Jan 2026).

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 (Liu et al., 3 Jan 2026).