OpenSeesMatlab

OpenSeesMatlab wraps the OpenSees engine in a native MATLAB interface for structural analysis and simulation. It provides integrated modeling, analysis, post-processing, and visualization tools for research and engineering applications in structural, earthquake, and geotechnical engineering.

Documentation

https://openseesmatlab.readthedocs.io/en/latest/

OpenSees Integration

OpenSeesMatlab leverages MATLAB's C++ mex interface to encapsulate the OpenSees engine, enabling seamless and interactive use of OpenSees directly within MATLAB. This allows users to:

• Run OpenSees commands and analyses natively in MATLAB scripts and functions
• Benefit from MATLAB's interactive environment for pre/post-processing and visualization
• Integrate OpenSees with MATLAB toolboxes and workflows

Installation

1. Open GitHub Releases or Gitee Releases, then download only the package for your computer:

   • Windows x86-64: OpenSeesMatlab-<version>-win64.mltbx
   • macOS Apple silicon: OpenSeesMatlab-<version>-maca64.mltbx

2. Put the downloaded .mltbx and installOpenSeesMatlab.m in one directory, open that directory in MATLAB, and run:

   installOpenSeesMatlab

After installation, explore and run example models in the examples/ directory (use it as the MATLAB working directory):

• Open any .m file in examples/ with MATLAB Live Editor, e.g.:
  • examples/earthquake_NLSMRF.m
  • examples/earthquake_Two_Story_Steel_MRF.m
  • examples/earthquake_frame3D_transient.m
  • examples/structural_nonlinear_truss.m
  • examples/geotechnical_PM4Sand.m
  • examples/post_2d_Portal_Frame.m
• Click "Run" in MATLAB to execute and interact with the example.

The generated scripts and illustrated walkthroughs are also available in the online examples.

Quick Start

Using OpenSeesMatlab is straightforward:

• The opensees module provides wrappers for almost all OpenSees commands, keeping the same parameter parsing style as OpenSees/OpenSeesPy.
• Modules such as vis, post, and pre extend functionality with visualization, post-processing, and preprocessing tools, which can be used as needed.

opsMat = OpenSeesMatlab();   % Get instance
ops = opsMat.opensees;       % Access OpenSees command interface

ops.wipe();
ops.model('basic', '-ndm', 2, '-ndf', 3);

ops.node(1, 0.0, 0.0);
ops.node(2, 5.0, 0.0);
ops.fix(1, 1, 1, 1);

A = 2.e-3;
Iz = 1.6e-5;
E = 200.e9;
ops.element('elasticBeamColumn', 1, 1, 2, A, E, Iz, 1)

...

opsMat.post.getModelData();  % Collect model data
opsMat.vis.plotModel();      % Visualize the model

OpenSeesMatlab() selects the serial backend by default. Run an OpenSeesSP model through the bundled OpenSeesSPMatlab launcher; it discovers MATLAB and common MPI installations and selects the SP backend inside the launched job. OpenSeesMatlab(backend="sp") is intended for that configured MPI process, not for switching an already initialized interactive session. The top-level object reports the interface and engine versions separately as bindingVersion and openseesVersion; version remains an alias of bindingVersion for existing code.

OpenSeesMatlab Extensions

Optional extensions integrate MATLAB-native components and GPU acceleration with the standard OpenSees analysis workflow:

• Recover failed nonlinear steps with adaptiveAnalyze
• Compute sparse linear buckling factors and mode shapes with linearBuckling
• Define linear or history-dependent uniaxial materials with MATLAB callbacks
• Couple MATLAB numerical substructures to an OpenSees domain
• Solve supported sparse systems with the NVIDIA cuDSS GPU backend, including CPU crossover, configurable ordering/pivoting, hybrid execution, single-node multi-GPU and Schur-complement controls

See the extension guides for setup instructions and runnable examples. CUDA and cuDSS are optional; CPU solvers remain available without them.

These extensions have targeted tests and examples, but they have not yet received the same breadth of independent use as established upstream OpenSees features. Verify critical numerical results against benchmarks or an independent formulation. Please report reproducible problems through GitHub Issues.

🌟 Features

• 🧱 .opensees — MATLAB interface to OpenSees commands (fully compatible syntax), implemented via MATLAB MEX wrapping of the OpenSees C++ library
• 📊 .post — post-processing module for extracting, organizing, and exporting analysis results
• 🏗️ .pre — preprocessing tools for model definition, units, and data preparation
• 🎨 .vis — visualization engine for models, responses, and mode shapes
• 📈 .anlys — high-level analysis workflows and utilities
• 🛠️ .utils — auxiliary helper functions and common utilities
• 🧩 Extensions — MATLAB-defined materials and numerical substructures, plus an optional NVIDIA cuDSS solver

Requirements

• Windows x86-64: MATLAB R2023a or later
• macOS Apple silicon: native MATLAB R2023b or later

Intel-based macOS and Linux MATLAB are not currently distributed.

License

This project is licensed for academic research and personal use only. Commercial and closed-source use is prohibited. See the LICENSE file for details.