> For the complete documentation index, see [llms.txt](https://tlcfem.gitbook.io/suanpan-manual/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://tlcfem.gitbook.io/suanpan-manual/readme.md).

# Introduction

This repository contains the official user documentation for [suanPan](https://tlcfem.github.io/suanPan/). For an optimized reading experience, users browsing this GitHub repository are encouraged to visit the web-based [documentation](https://tlcfem.github.io/suanPan-manual/latest/).

As an alternative, a continuously updated version is hosted on [gitbook](https://tlcfem.gitbook.io/suanpan-manual/). 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](https://github.com/TLCFEM/suanPan-manual/tree/dev/docs/SUMMARY.md). For insights into the software's underlying software engineering paradigms and system architecture, please refer to the technical [slides](https://github.com/TLCFEM/suanPan-manual/tree/dev/docs/ARCH.pdf).

## Motivation and Core Advantages

The development of [suanPan](https://tlcfem.github.io/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](https://tlcfem.github.io/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](https://tlcfem.github.io/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](https://tlcfem.github.io/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](https://tlcfem.github.io/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](https://tlcfem.github.io/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](/suanpan-manual/basic/analyze.md), followed by the foundational architectural overviews in [Syntax](/suanpan-manual/basic/syntax.md) and [Structure](/suanpan-manual/basic/structure.md).

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

* [>Linear Analysis of A Truss Roof<](/suanpan-manual/example/structural/statics/truss-roof.md)
* [>Dynamic Analysis of A Portal Frame<](/suanpan-manual/example/structural/dynamics/dynamic-analysis-of-a-portal-frame.md)

Detailed command syntaxes and programmatic entities are catalogued across the `Collection` and `Library` sections. To streamline workflow productivity, a dedicated VS Code [extension](https://marketplace.visualstudio.com/items?itemName=tlc.suanpan) is available, providing syntax highlighting and auto-completion capabilities.

Additionally, the comprehensive test suite in the repository's [Example](https://github.com/TLCFEM/suanPan/tree/dev/Example) directory provides an exhaustive reference of validated input configurations.

## Collaborative Contribution

Contributions to the [suanPan](https://tlcfem.github.io/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](/suanpan-manual/basic/build.md).

## Citation

If [suanPan](https://tlcfem.github.io/suanPan/) facilitates or supports your research publications, please cite the framework via its registered DOI at [10.5281/zenodo.1285221](https://doi.org/10.5281/zenodo.1285221), selecting the version appropriate to your work.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://tlcfem.gitbook.io/suanpan-manual/readme.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.