Skip to content

Introduction

This repository contains the official user documentation for suanPan. For an optimized reading experience, users browsing this GitHub repository are encouraged to visit the web-based documentation.

As an alternative, a continuously updated version is hosted on gitbook. Note, however, that certain dynamically generated components may be absent in the GitBook version due to platform limitations regarding Jupyter Notebook conversions.

This documentation remains under active development. Users are invited to submit issues via GitHub to report gaps in information or seek clarification.

A comprehensive overview of the manual is available via the table of contents. For insights into the software's underlying software engineering paradigms and system architecture, please refer to the technical slides.

Motivation and Core Advantages

The development of suanPan is driven by two critical architectural requirements: flexibility and high performance.

While commercial finite element analysis (FEA) software packages offer robust capabilities, they are often constrained by prohibitive licensing costs, limiting access for individual researchers and smaller institutions. Furthermore, implementing novel constitutive models or element formulations in traditional commercial environments (e.g., via C/Fortran user subroutines) is frequently hindered by legacy programming constraints and laborious tensor algebra implementations. Conversely, many open-source alternatives are tailored to narrow domains or lack comprehensive multi-dimensional modelling capabilities. For instance, packages like OpenSEES primarily optimize for uniaxial frame structures, offering limited support for complex 2D and 3D continuum mechanics.

suanPan addresses these challenges by integrating cutting-edge research into a unified, high-performance platform. The framework provides an extensive, multi-domain library comprising:

  1. Advanced Element Formulations: A comprehensive suite of 1D, 2D, and 3D elements incorporating modern finite element techniques;
  2. Constitutive Models: High-fidelity uniaxial and multiaxial nonlinear material models for metals, concrete, timber, geomaterials, etc.;
  3. Advanced Numerical Solvers: State-of-the-art solution routines and modern time-integration schemes;
  4. Extended Domain Capabilities: Additional specialized modelling features.

To maximize computational efficiency, suanPan natively exploits modern multi-core processor architectures with hybrid parallelization. Key pipeline operations, including element/material state determination, global matrix assembly, and constraint enforcement, are fully parallelized. Consequently, the framework systematically outperforms conventional single-threaded or distributed-memory MPI-based packages on modern workstation hardware.

Built on modern C++ and powered by the Armadillo linear algebra library, suanPan offers an expressive API where core structural code closely mirrors the underlying mathematical expressions. This significantly lowers the barrier to entry for researchers implementing and validating novel computational mechanics theories.

suanPan delivers distinct architectural and operational advantages over alternative finite element packages:

Operational Efficiency & Functional Scope (User Perspective)

  • Declarative Workflow: Eliminates the overhead of complex scripting, streamlining model preparation and execution.
  • Native Parallelization: Fully parallelized execution pathways significantly accelerate computational throughput and shorten engineering design cycles.
  • Extensive Library Ecosystem: Provides a comprehensive suite of advanced element formulations and constitutive material models absent in conventional packages.

Research Agility & Extendability (Developer Perspective)

  • Modular Architecture: Minimizes data coupling via a highly decoupled, modular design to facilitate rapid prototyping and algorithmic experimentation.
  • Mathematical Expressiveness: Leverages high-level abstractions that closely mirror underlying tensor and matrix algebra, simplifying the implementation of complex multiaxial models.
  • Reduced Cognitive Load: Employs built-in structural scaffolding to manage low-level internal routines, allowing researchers to focus exclusively on core mechanics.

Getting Started

The input file logic in suanPan shares syntax paradigms with ABAQUS, enabling users familiar with commercial software to transition efficiently.

To establish a baseline understanding, users should review the initial demonstration in Analyze, followed by the foundational architectural overviews in Syntax and Structure.

For practical applications, the Example section offers a tiered learning path ranging from introductory benchmarks to complex simulations. Recommended entry points include:

Detailed command syntaxes and programmatic entities are catalogued across the Collection and Library sections. To streamline workflow productivity, a dedicated VS Code extension is available, providing syntax highlighting and auto-completion capabilities.

Additionally, the comprehensive test suite in the repository's Example directory provides an exhaustive reference of validated input configurations.

Collaborative Contribution

Contributions to the suanPan ecosystem are highly encouraged. Feature requests or inquiries regarding the implementation of specific elements or material models can be directed to the core development team.

Documentation improvements, including errata and clarifications, should be submitted as pull requests or tracking issues. Documentation contributions for third-party libraries must consist of a self-contained markdown file outlining usage guidelines and relevant theoretical foundations. Detailed instructions for local compilation of this manual are provided in Build.

Citation

If suanPan facilitates or supports your research publications, please cite the framework via its registered DOI at 10.5281/zenodo.1285221, selecting the version appropriate to your work.