SeismicLSTM: LSTM Networks for Nonlinear Structural Systems

LSTM Network Architecture for Seismic Structural Analysis

📋 Table of Contents

• Overview
• Abstract
• Features
• Installation
• Quick Start
• Usage
• Results
• Project Structure
• Contributing
• Citation
• License

🎯 Overview

This repository implements Long Short-Term Memory (LSTM) networks for surrogate modeling of nonlinear structural systems under seismic excitation. The project addresses the computational challenges in performance-based seismic design (PBSD) by providing fast, accurate, and reliable surrogate models for structural response prediction.

📖 Abstract

Performance-based seismic design (PBSD) of structural systems relies on computationally expensive high-fidelity finite element (FE) models to predict how structures will respond to seismic excitation. For risk-based assessments, FE response simulations must be run thousands of times with different realizations of the sources of uncertainty. Consequently, data-driven machine learning (DDML) surrogate models have gained prominence as fast emulators for predicting seismic structural responses in probabilistic analyses.

This paper leverages deep Long Short-Term Memory (LSTM) networks, known for their powerful and flexible framework for time series prediction tasks. The advantages of using LSTM networks include:

• ✅ Continuous-time modeling of structural dynamics
• ✅ Adaptive temporal resolution handling
• ✅ Implicit memory of past information
• ✅ Complex nonlinear dynamics modeling
• ✅ Interpolation and extrapolation capabilities
• ✅ Robust noise handling
• ✅ High-dimensional dataset scalability

The effectiveness of the proposed method is validated through three proof-of-concept studies:

1. Linear elastic 2D 8-degree-of-freedom (DoF) shear building model
2. Nonlinear single degree of freedom system (NL-SDoF)
3. 2D nonlinear 3DoF shear building model

✨ Features

• 🚀 Modular Architecture: Clean, maintainable code structure
• 🔧 Multiple Model Types: Base, Model A, and Model B architectures
• 📊 A/B Testing: Compare different model architectures
• 📈 Training Visualization: Real-time loss plotting and history tracking
• 💾 Model Persistence: Save and load trained models and scalers
• 🎛️ Configurable Parameters: Easy hyperparameter tuning
• 📋 Comprehensive Logging: Detailed training progress and metrics

🛠️ Installation

Prerequisites

• Python 3.8 or higher
• pip package manager

Setup

1. Clone the repository

   git clone https://github.com/ymorsi7/SeismicLSTM.git
   cd SeismicLSTM

2. Install dependencies

   pip install -r requirements.txt

3. Verify installation

   python -c "import tensorflow as tf; print(f'TensorFlow version: {tf.__version__}')"

🚀 Quick Start

Basic Usage

Train a base LSTM model with default parameters:

python main.py --data_file data_2DOF_SB_BWWN.mat --model_type base --epochs 10

A/B Testing

Compare Model A and Model B architectures:

python main.py --data_file data_2DOF_SB_BWWN.mat --ab_test --epochs 10

📖 Usage

Command Line Arguments

Argument	Type	Default	Description
--data_file	str	data_2DOF_SB_BWWN.mat	Path to MATLAB data file
--model_type	str	base	Model type (base, A, B)
--epochs	int	10	Number of training epochs
--batch_size	int	5	Batch size for training
--ab_test	flag	False	Perform A/B testing
--save_dir	str	results	Directory to save results

Example Commands

# Train Model A with custom parameters
python main.py --model_type A --epochs 20 --batch_size 10

# Train Model B and save to custom directory
python main.py --model_type B --save_dir my_results

# Quick A/B test with 5 epochs
python main.py --ab_test --epochs 5

📊 Results

The results demonstrate the effectiveness of LSTM networks for seismic structural analysis across different structural configurations:

Test-bed Structures

Test-bed structures for surrogate modeling study

Performance Results

1. Linear Elastic 8-Story Shear Building

2. Nonlinear Inelastic Single Degree Of Freedom (SDOF) Structure

3. Nonlinear Inelastic Multi Degree Of Freedom (MDOF) Structure

4. A/B Testing Comparison

📁 Project Structure

SeismicLSTM/
├── 📁 src/                          # Source code
│   ├── 📁 data/                     # Data handling
│   │   └── data_loader.py          # Data loading and preprocessing
│   ├── 📁 models/                   # Model architectures
│   │   └── lstm_models.py          # LSTM model definitions
│   └── 📁 utils/                    # Utilities
│       └── training.py             # Training utilities
├── 📁 files/                        # Documentation and images
│   ├── 📄 paper.pdf                # Research paper
│   ├── 🖼️ testbed.png              # Test-bed structures
│   ├── 🖼️ lstm.png                 # LSTM architecture
│   ├── 🖼️ 1.png                    # Linear elastic results
│   ├── 🖼️ 2.png                    # SDOF results
│   ├── 🖼️ 3.png                    # MDOF results
│   └── 🖼️ ab.png                   # A/B testing results
├── 📄 main.py                       # Main training script
├── 📄 requirements.txt              # Python dependencies
├── 📄 .gitignore                    # Git ignore rules
└── 📄 README.md                     # This file

📚 Detailed Report

For comprehensive analysis and detailed results, please refer to our research paper:

📄 Read the Full Paper

🤝 Contributing

We welcome contributions! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.

Contributing Guidelines

1. Fork the repository
2. Create a feature branch (git checkout -b feature/AmazingFeature)
3. Commit your changes (git commit -m 'Add some AmazingFeature')
4. Push to the branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

📄 Citation

If you use this code in your research, please cite our paper:

@article{seismiclstm2024,
  title={Application of Long Short-Term Memory (LSTM) Networks-Based Surrogate Modeling for Nonlinear Structural Systems},
  author={Coulibaly, Abdoul Aziz Sandotin and Zeballos, Enrique Simbort and Morsi, Yusuf and Sarange, Ramin},
  journal={Journal of Structural Engineering},
  year={2024},
  doi={10.1000/xyz}
}

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

👥 Authors

• Abdoul Aziz Sandotin Coulibaly - Lead Researcher
• Enrique Simbort Zeballos - Research Contributor
• Yusuf Morsi - Research Contributor
• Ramin Sarange - Research Contributor