ReplicaXLite: A Finite Element Toolkit for Creating, Analyzing and Monitoring 3D Structural Models

Abstract

The need for reliable software for data acquisition, processing and communication with laboratory instruments, as well as for extending laboratory findings to real-scale structures, is imperative. In this context, ReplicaXLite is presented: an open-source software framework designed to facilitate and organize structural experimental testing on seismic tables. The software enables the creation of digital twin models and real-time sensor data recording. Furthermore, it allows for the processing, storage and visualization of results within a graphical interface. It features two primary modes of operation: (a) via terminal with specific Application Programming Interfaces (APIs) and (b) via a Graphical User Interface (GUI), adapting to the user’s expertise level. The software lies on top of open-source libraries like OpenSeesPy and opstool. It supports many material types, such as concrete, steel, fibers and composites, among others. Models produced by ReplicaXLite demonstrate strong agreement with experimental data across varying structural configurations. For both acceleration and displacement, the framework yielded satisfactory accuracy at the top slab with mean envelope correlations ranging from 0.91 to 0.97 and mean Pearson correlations generally between 0.83 and 0.95 for varying seismic intensities (0.1 g to 1.4 g). The numerical framework successfully captured global stiffness degradation, with Normalized Root Mean Square Errors (NRMSE) well-constrained between 2.3% and 7.9% across both acceleration and displacement response metrics. The architecture allows for the one-click execution of custom user codes, providing full access to the source code and the ability to perform live toolkit modifications via the “app.” terminal variable. Finally, it provides mid-simulation modification of the mass and elements of the model.

1. Introduction

Structural components or complex systems have long relied on OpenSees [1] as a robust computational engine for advanced numerical investigations [2,3,4,5,6,7,8,9,10]. However, the effective utilization of OpenSees often necessitates supplementary tools to bridge the gap between code-based analysis and visual interpretation [11]. FeView (v1.0) [12] represents a significant effort in this domain, offering an open-source, Python (v3.7)-based Graphical User Interface (GUI) specifically tailored for Finite Element Model (FEM) visualization. This tool focuses on post-processing tasks, enabling users to generate contour plots, nodal response graphs and response spectrum analyses. With support for over 46 element types and a wide array of material models, FeView integrates Tcl scripting for model definitions and leverages PyVista (v0.25.3) [13] for real-time visualization. However, it lacks native pre-processing capabilities as users need to manually script Tcl files for model generation (without proper automatic help). Similarly, OpenSeesPyView (v0.1.0) [14] has been developed to address the visualization needs of the community. While it provides essential plotting functionality, its primary focus remains on post-processing rather than model creation, leaving a gap for users seeking a fully visual interface for defining structural geometry and properties from scratch.

To address the complexities of model generation, the GiD+OpenSees Interface (v2.9.6) [15] was introduced as an open-source add-on that links the OpenSees solver with GiD, a general-purpose commercial pre- and post-processor. This interface significantly lowers the barrier to entry by allowing users to define geometry, assign boundary conditions, and select analysis protocols within a graphical environment. However, while the add-on itself is free, the dependence on the commercial GiD software introduces potential licensing costs, which limits its accessibility compared to fully open-source solutions.

More recently, the opstool (v1.0.19) library [16] has emerged as a powerful open-source Python package designed to streamline the OpenSeesPy [17] workflow. This library enhances data management through xarray (v 2025.10.1) [18] integration and enables advanced, interactive 3D visualizations via PyVista (v 0.44.1) and Plotly (v6.3.1) [19]. Beyond visualization, opstool incorporates adaptive algorithms to improve convergence in nonlinear analyses and simplifies the comparison of results with commercial software like SAP2000 [20], effectively serving as a comprehensive toolkit for finite element modeling. In addition to frame-oriented tools, high-fidelity FEA packages such as Abaqus and Ansys, etc., are frequently employed to predict the detailed structural behavior of reinforced concrete elements, offering high-resolution insights into localized failure mechanisms that complement the broader structural assessments provided by OpenSees [21,22,23].

Despite these significant advancements in numerical pre- and post-processing, a critical review [11] of the current OpenSees ecosystem reveals a major gap: existing GUIs and toolkits are exclusively designed for static, purely numerical simulations. The architecture required to handle the direct ingestion, synchronization, and near real-time processing of physical sensor data from a laboratory environment is still challenging.

Building upon the advanced capabilities of opstool, this study presents ReplicaXLite (v1.0.0), a novel hybrid platform developed within the GREENERGY project, primarily to serve the seismic table of the Reinforced Concrete and Seismic Design of Structures Laboratory at Democritus University of Thrace. The primary novelty and contribution of this work lie in bridging the gap between physical experiments and numerical modeling. Unlike existing interfaces that focus on numerical simulation, ReplicaXLite is designed to facilitate the near real-time integration of sensor data processing with Finite Element Analysis (FEA), using OpenSeesPy as the underlying solver. The platform is structured around four distinct Application Programming Interfaces (APIs) that allow it to function in both a Command Line Interface (CLI) for advanced scripting and a user-friendly GUI mode for training and streamlined analysis. By seamlessly combining Structural Health Monitoring (SHM) capabilities with advanced nonlinear structural analysis, ReplicaXLite provides a unique, accessible framework for hybrid testing and digital twinning. A comparison of functionalities demonstrating this shift from purely numerical tools to a hybrid, laboratory-integrated platform is depicted in

Table 1. Feature comparison of ReplicaXLite with prominent open-source OpenSees packages [11].

Software Package	Primary Target Application	Interface/ Environment	3D Modeling (Pre- Processing)	3D Visualization (Post- Processing)	Automated Complex FEA *	Physical Sensor Integration	Real-Time SHM & Lab Data Processing
DYANAS	SDOF Systems	MATLAB GUI	No (2D only)	No (2D only)	M.G.T.	No	No
FeView	General FEM Visualization	Python GUI	No (Requires script)	Yes	M.G.P.T.	No	No
FM-2D	2D Steel & RC Frames	MATLAB GUI	No (2D only)	No (2D only)	M.G.P.T.	No	No
GID + OpenSees	General FEM	GiD Add-on	Yes	Yes	M.G.P.T.	No	No
Hyperomet	Unreinforced Masonry	Tcl Wrapper	No (2D only)	No	M.G.P.T.	No	No
INSPECT-SPSW	Steel Plate Shear Walls	Standalone GUI	No (2D only)	No (2D only)	M.G.P.T.	No	No
OpenSeesPyView	General FEM Visualization	Python GUI	Yes	Yes	M.G.T.	No	No
opstool	Python FEM Workflow Optimization	Python Library	Yes (via Scripting)	Yes	M.G.P.T.	No	No
ReplicaXLite (Proposed)	Hybrid FEA & Laboratory SHM integration	Python CLI & GUI	Yes	Yes	M.G.P.T.	Yes	Yes

* M. = Modal, G. = Gravity, P. = Pushover, T. = Transient.

.

2. ReplicaXLite Architecture

The core code that provides the main API of ReplicaXLite includes the StructuralAPI, SensorsAPI, UnitsAPI and DataValidationAPI, described in the following sections.

2.1. Structural API

The Structural API is built as a high-level object-oriented layer of OpenSeesPy that focuses on fast and organized creation, storage and modification of the model components. The core novelty of the framework lies in its Delayed Execution Mechanism (DEM). Unlike standard scripts that send commands to the solver sequentially, this API constructs an intermediate object graph within the Python environment. Structural components—nodes, elements, materials, and constraints—are instantiated as independent objects with their own properties and methods. This allows the user to manipulate the model geometrically (e.g., translation, rotation, subdivision) and topologically (e.g., node merging, duplicate, removal) before the finite element domain is initialized. The system only “compiles” this object graph into OpenSees commands during a specific build phase, ensuring that the numerical model is geometrically consistent and optimized prior to analysis.

The framework implements a robust geometry engine capable of handling both explicit generation (algorithmic grids) and implicit importation. A significant feature is the integration of Computer-Aided Design (CAD) workflows via DXF interoperability. The system parses vector layers from CAD files, sorting entities by spatial priority and mapping them to specific structural element groups (for more detailed information please see GitHub help section).

The definition of cross-sections is handled through a parametric fiber generation engine. Rather than requiring the manual input of coordinate matrices for every fiber, the system utilizes shape-based definitions (e.g., T-section, I-section, Circular, User-Defined). For reinforced concrete applications, the framework abstracts rebar placement into logical groups (lines, circles, points), automatically calculating the discrete fiber coordinates and associated material tags. This module supports both elastic integration and complex fiber-discretized sections, handling the mathematical transformations required for geometric centroid alignment and local coordinate rotation.

To address the complexities of nonlinear simulation, the framework incorporates a hierarchical analysis manager. This module orchestrates the simulation as a sequence of dependent stages—typically progressing from eigenvalue to gravity analysis and finally to lateral inelastic (nonlinear) static (pushover) or dynamic time–history inelastic (nonlinear) analysis. The system integrates robust adaptive stepping algorithms (“Smart Analysis”) of the opstool library to mitigate convergence failures common in nonlinear mechanics property.

Visualization is embedded directly into the modeling workflow using high-performance VTK-based [24] rendering. The framework provides methods to visualize not just the undeformed geometry but also the analytical output, including mode shapes, deformed configurations and internal force diagrams. Furthermore, the system encapsulates results into structured output databases (ODB), facilitating efficient data retrieval and post-analysis processing (a feature that is available in the opstool library).

The high abstract overview of the Structural API code is provided in Figure 1.

2.2. Sensors API

The ReplicaXSensorDataReader class provides a robust pipeline (see Figure 2a) for initializing, conditioning and analyzing time-series sensor data. It bridges the gap between the raw CSV/Excel extract from various sensors and automatic universal operations like unit conversion, signal processing and comparative filter analysis. The data reader operates in a strict sequence of correction operations defined in a JSON/Dictionary configuration (see Figure 2b). The class executes correction modules in a specific, immutable order to ensure mathematical consistency (e.g., resampling must occur before filtering). The main JSON file configurations are presented in

Table 2. ReplicaXSensorDataReader class JSON config file content.

Parameter	Type	Description
file_path	str	Absolute path to the source CSV file.
separator	str	CSV delimiter (e.g., ”,”, ”;”).
start_row	int	Excel-based row index (1-based) where data starts.
end_row	int	Excel-based row index (1-based) where data ends.
time_column	str	Excel column letter for the Time vector (e.g., ”A”).
dt	float	Expected time step.
data	dict	Map of internal ID to Excel Column (e.g., {“S1”: “B”}).
data_name	dict	Map of internal ID to Custom Name (e.g., {“S1”: “Accel_Top”}).
input_units	dict	{“time”: “s”, “data”: “g”}
output_units	dict	{“time”: “s”, “data”: “m/s^2”}
data_correction	dict	Data corrections dictionary for in depth information see source-code or help file in the repository.

. For the filter part the class provides everything from a simple moving average for a simple rolling mean to a Savitzky–Golay filter that may preserve the peak height while smoothing the noise. The code utilizes the scipy.signal [25] for advanced Infinite Impulse Response (IIR) filters including butterworth, chebyshev1, chebyshev2, elliptic and bessel. For in depth understanding of the filter implementation please see [25]. A specific section of the class is dedicated to the Filter Comparison Engine. It allows the user to test multiple filter configurations against a reference signal to determine the optimal processing strategy. The workflow includes (a) FFT Analysis: Computes frequency spectrum of the raw signal; (b) Peak Detection: Identifies dominant frequencies (Top N peaks); (c) Batch Processing: Applies multiple filter configs temporarily; (d) Metric Calculation: Computes signal quality metrics; and (e) Ranking: Weighted scoring to recommend the best filter. The report can be exported as HTML.

The system is designed to support sensor data updates with a minimum latency of 100 ms. However, the default update interval is configured to 1000 ms to incorporate safety protocols related to input/output permissions and server/file access during data retrieval. Users are advised to evaluate and optimize this latency setting based on their specific application requirements and to verify that the underlying data source supports concurrent read and write operations.

To further clarify the digital twin integration capabilities, the framework supports near real-time bidirectional feedback rather than continuous, instantaneous real-time control. While sensor data ingestion can occur rapidly as described, data export from the digital twin—used to interpret partial information or inform the physical experiment—is performed in near real-time. Crucially, this bidirectional interaction operates sequentially; the numerical simulation must complete its current active analysis stage (e.g., a gravity analysis, a pushover step, or an individual time–history excitation) and successfully save its simulated state before it can interact with the experimental equipment. Consequently, synchronization between the physical sensors and the digital model is achieved on a step-by-step, near real-time basis.

2.3. Units API

The ReplicaXUnits module serves as the centralized handling mechanism for physical quantities within the finite element toolkit, ensuring numerical consistency across diverse measurement systems. The architecture is built upon a reference-base approach, where the International System of Units (SI) is primarily utilized as the internal normalization standard. Rather than maintaining a complex matrix of direct conversion factors between every possible pair of units, the system maps each specific unit to a unique scaling factor relative to its governing base quantity (e.g., meters for length, Newtons for force). As illustrated in Figure 3, the conversion process is a two-step linear transformation: the input value is first normalized to the base unit and subsequently projected into the target unit system. This design decouples the unit definitions from the conversion logic, allowing for the seamless integration of new measurement standards—such as US Customary or Imperial units—without altering the underlying solver algorithms. Additionally, the module includes specialized handling for nonlinear transformations, specifically required for temperature conversions involving zero-point offsets.

2.4. Data Validation API

To guarantee numerical stability within package, the ReplicaXDataTypesManager may function as a strict validation layer for all incoming data. As detailed in Figure 4, the module employs a bifurcated logic flow depending on the target schema. For primitive inputs, the system enforces rigid type distinctions (explicitly rejecting floating-point values for integer fields) to prevent unwanted behaviors. For complex data structures (such as lists or dictionaries), the engine first attempts to deserialize raw measuring inputs (often received as JSON or string literals) into Python objects. It then executes a recursive validation loop, verifying that every nested element conforms to the specified type signature. This ‘schema-first’ approach ensures that malformed data is rejected at the ingestion stage, preventing runtime exceptions during the computationally intensive analysis phase.

2.5. Graphical User Interface (GUI)

Upon launching the application, the main user interface appears as illustrated in Figure 5. The main window is divided into four distinct dynamic sections under the Setup tab, (a) Project File Viewer, (b) Center Panel, (c) Console Panel, and (d) Status Bar, alongside one static element, the Main Menu.

The Project File Viewer functions as the project file manager. It allows users to search for files and refresh the project content to reflect any additions, deletions or modifications. It also provides the capability to execute Python files directly in the console via double-click, facilitating project automation and customization.

The Center Panel is divided into two sections. The top section contains an interactive 3D visualization environment utilizing a right-hand Cartesian coordinate system. This serves as the primary workspace for viewing and manipulating models (using PyVista-based rendering). The bottom section contains the FEM table-tabbed interface, designed primarily to help new users familiarize themselves with StructuralAPI commands, thereby preparing them for more complex and sequential analyses using the API. The final tab refers to the Sensors module; built upon the SensorsAPI, it provides capabilities for viewing, interpreting and filtering spatial coordinates and raw data.

The Console Panel—the software’s most powerful tool—grants the user full access to the source code at any time, as well as access to the GUI itself via the “app.” command within the terminal. This allows users to perform complex tasks in a manner similar to running the program in CLI mode with API interactions.

Finally, the static Main Menu includes the Project menu (for creating, opening, or closing a project, accessing settings and exiting the program); the View menu (which provides navigation options within the interactor, such as moving, rotating and toggling view types based on user preferences); and the Tools menu (which offers access to specific standalone applications like Sensors, Unit Converter and Color Picker). This description is summarized in

Table 3. Explanation of ReplicaXLite main window dynamic components.

Panels	Description
1. Left Panel: Project File Viewer	Tree-view navigation of project files and structure.
2. Center Panel: Split into Two Sections
Top Section—3D Interactor:	PyVista-based interactive 3D workspace for model viewing and manipulation.
Bottom Section—FEM Tables	Materials: Define elastic and fiber sections. Nodes: Configure coordinates, constraints, restraints, masses. Components: Set elements, time series, patterns, analyses, and sensors.
3. Right Panel: Console	Jupyter-based Python environment for direct application control. Execute scripts and view messages. Supports rich media display (plots, LaTeX).
4. Status Bar	Displays current application state, operation status, and notifications.

. For further information, users may refer to the Help section in the GitHub Repository.

3. Detailed Seismic Table Example

The numerical implementation concerns experiments conducted on the shake table at Democritus University of Thrace (DUTh) in Xanthi, Greece, which are detailed in [26,27] for the Phase A and Phase B experimental setups. A brief description of the reinforcement configuration and material properties is presented here, as these are necessary for the numerical model inputs. Further detailed information can be found in [26,27].

3.1. Experimental Parameters of As-Built Building in Phase A

Phase A of the DUTh shake table experiments employed a 1:3 scaled, single-story reinforced concrete frame (2.70 m × 2.70 m plan, 1.95 m height, mass 4.3 tonnes) designed to replicate deficient pre-Eurocode, Greek (or southern European) construction. The specimen intentionally incorporated critical flaws: C20/25 concrete columns with inadequate transverse reinforcement (4∅8 mm ribbed longitudinal bars, ∅5.5/60 mm smooth stirrups), low-strength masonry infills (clay bricks with 10 mm lime–cement mortar bed joints), and partial versus full infill layouts aligned with the seismic loading directions (see Figure 6 for the geometry and reinforcement of the typical frame). These features simulated inadequate existing buildings to assess innovative retrofit techniques in Phase B.

3.2. Experimental Parameters of Vertical Forest Renovated Building in Phase B

In Phase B, the Phase A as-built specimen was renovated using a vertical forest strategy, featuring innovative retrofits. These included basalt fiber rope confinement on critical regions of the columns, polyurethane flexible (seismic) joints (PUFJ) between all infill-concrete interfaces and one-sided fiber-reinforced polyurethane (FRPU) jackets with a fiberglass grid on cracked masonry infills. This integration incorporated eight steel-frame vertical living walls (40 kg/m² mass density) and five concrete planters on the top slab (795 kg total), simulating realistic greenery loads for seismic validation. The retrofit prioritized natural, recyclable materials acting as damage barriers to minimize non-recyclable resource use while optimizing the brick infill-column interaction. All interventions activated rapidly (within 30 min to several hours), enabling exceptional emergency deployment without compromising structural safety. For further details, see [27].

3.3. ReplicaXLite Structural API Setup

The first step in initializing the model is to import the StructuralModel class from the ReplicaXLite package. Afterward, an instance of the class is created and initialized with model = StructuralModel(“UserDefinedName”). The user can assign any arbitrary name to the model, which serves as a personal reference. Next, the user defines the material and cross-section properties using the model.properties.create_uniaxial_material() and model.properties.create_fiber_section() functions. With create_uniaxial_material, the user can create any uniaxial material available in the OpenSees library. The user must provide an integer tag (ID) for the material, followed by an internal name (unrelated to OpenSees) for future reference. For the material_type, the exact OpenSees material name must be entered, strictly observing case sensitivity. Any necessary properties are provided in a dictionary (key-value) format via material_args. For example, Figure 7 shows the code snippet for the reinforcement steel used in the longitudinal rebars. Herein, all properties are defined based on experimental data.

Following the same approach used for the reinforcement, the user assigns the Concrete02 material to all concrete and infill sections. The basic material properties for each concrete part are provided in

Table 4. Basic material properties for concrete definition.

Element	Material	fpc (kPa)	epsc0 (-)	fpcu (kPa)	epsU (-)
base_beam_cover	Concrete02	36,760	0.002	7350	0.0035
base_beam_core	Concrete02	37,760	0.002	7350	0.004
column_cover	Concrete02	24,820	0.002	4960	0.0035
column_core	Concrete02	25,820	0.002	4960	0.004
slab_cover	Concrete02	31,630	0.002	6330	0.0035
slab_core	Concrete02	32,630	0.002	6330	0.004

. The material parameters for Steel02 and Concrete02 were derived directly from experimental stress–strain data. In the Concrete02 material model, damage is not represented by a single scalar variable but is implicitly calculated through the degradation of unloading and reloading stiffness based on strain history. In compression, damage is tracked using the maximum previous compressive strain (ecmin), where the unloading slope is determined by the input parameter λ (lambda), dictating the stiffness reduction relative to the initial elastic modulus. For post-crack tensile behavior, the model initiates cracking once the tensile strength (ft) is exceeded, following a linear softening branch defined by the softening stiffness Ets. Finally, the tensile and compressive damage states are coupled, as the residual strain from compressive unloading shifts the tensile envelope, ensuring that prior crushing directly influences the subsequent cracking response.

After defining the materials, the user defines each fiber cross-section. A code snippet for the column definition is provided in Figure 8. The Structural API can generate the proper fiber section for rectangular, T-shaped, Double-T, circular, and arbitrary user-defined cross-sections. The code allows the user to define reinforcement as individual fibers, along a specific line length, or in a circular pattern. This definition relies heavily on the opstool library. The concrete fiber cross sections are depicted in Figure 9.

This research adopts the unreinforced brick infill model proposed by Di Trapani et al. [28], as modified by Pradhan & Cavaleri [29] (see Figure 10 for the flowchart). The updated approach replaces pin connections with fixed-end connections for all struts to limit mid-span deflections and enhance the arching mechanism under out-of-plane (OOP) loading. To streamline calibration, the model applies unified material properties and surrogate thickness values across all struts (diagonal, horizontal, and vertical). Perhaps most significantly, the modified model replaces arbitrary property assignment with a systematic correlation method dependent on the product of the masonry compressive strength and elastic modulus $(f_m{E}_m$). This interaction parameter is used to derive the peak strength ($f_{m0}$), the strain at peak stress $\left({\mathsf{\epsilon }}_{m0}\right),$ and the ultimate strain $\left({\mathsf{\epsilon }}_{mu}\right)$ via specific polynomial and linear equations, while the ultimate residual strength $\left(f_{mu}\right)$ is explicitly established as 60% of the calculated peak strength $\left(f_{m0}\right).$

Regarding mass distribution, the total infill mass is lumped equally onto four mid-span nodes located at the panel’s geometric center.

These nodes operate under a critical constraint system: they displace independently in-plane to allow for complex stress distributions, yet remain rigidly connected out-of-plane to ensure the mass moves as a cohesive unit. This configuration captures the inertial effects and arching mechanism essential for OOP behavior. By applying lateral loads directly to these central nodes, forces are transmitted simultaneously through the constraint system to all struts, effectively activating the bending response in the fiber elements.

The next stage is the definition of the node geometry. The user can import this information from a text or configuration file using libraries like NumPy, or organize it in a dictionary format and pass it through a loop to prevent code repetition. A characteristic example of the node definition is provided in Figure 11a, where nodes are provided as Python dictionaries with unique node IDs as keys and the 3D Cartesian coordinates as values. The same technique is applied to the definition of the linear elements (see Figure 11b). However, the user must first define the integration scheme using the model.properties.create_beam_integration() function. Afterwards, the user creates the fixed nodes, equal degrees of freedom, plane diaphragms and masses, following the same logic used for the node definition.

When satisfied with the model definition, the user executes model.build_model(). During the execution of this function, the model properties are translated from the ReplicaXLite format into OpenSeesPy code. Once the code is properly defined, the user creates appropriate time series and load patterns to perform gravity, static, or pushover analyses. For time–history analyses, the Structural API internally creates the time series and patterns based on the time–history data provided by the user. Results are automatically saved in an opstool-defined database, allowing seamless retrieval using native opstool commands.

The final model with the local axes and the applied gravity loads ready for dynamic time–history analysis is provided in Figure 12a,b, respectively.

Similarly, for Phase B, a detailed geometry is created, and all steps described for Phase A are followed to update the model. Initially, the model is set to a ‘forced user-released’ state (Figure 13), meaning the user is responsible for the proper execution and order of any updates. Consequently, the user needs to possess deep knowledge of the codebase before attempting such actions. This state provides the user with the ability to alter the mass and modify, add, or delete elements from the initial model during sequential analyses without resetting the analysis. This approach ensures that material properties properly retain the accumulated damage state of the elements, matching the real scenario of sequential multiple-phase analyses (arising from different load, mass variation, or modeling variation phases). To maintain numerical stability and prevent the introduction of artificial dynamic shocks or unbalanced forces, this topological transition is specifically triggered during a state of relative kinetic rest. That is, the modification is executed when the structure exhibits nearly zero velocity and acceleration. Furthermore, this workflow is designed for scenarios where the structure has sustained relatively small permanent deformations, ensuring geometric and numerical compatibility when new elements are injected into the deformed mesh.

The final 3D model for the specimen and its graphical linear representation is depicted in Figure 14. Basalt rope confinement was simulated using a hollow fiber section and an Elastic-Perfectly Plastic (EPP) material model, characterized by negligible compressive strength and a suitable tensile modulus. The Vertical Living Wall (VLW) and planter pods were modeled as elastic steel and hollow sections, respectively, incorporating 50 mm square-section wood elements and distributed masses to represent vegetation.

Regarding the masonry retrofits, the FRPU surface retrofit was defined as a 3 mm external (one-sided) jacket using a mix-rule material model. Furthermore, the PUFJ seismic joint regions were transitioned from brick infill properties (Phase A) to an EPP material definition (E = 4 MPa, 110% elongation) in Phase B, with overlapping elements at strengthening nodes utilized to ensure accurate local and global interaction.

3.4. ReplicaXLite Structural API Dynamic Load Definition

The Phase A and Phase B models were excited sequentially with scaled versions of the Thessaloniki 1978 earthquake, as depicted in Figure 15. For the exact set of sequential excitations for each phase (a total of 39 different excitations, including white-noise excitation) please refer to [26,27].

4. Results

The numerical models were subjected to the exact seismic sequences recorded during the experimental campaigns. For Phase A (as-built), the excitation protocol consisted of 11 sequential dynamic tests (white noise excitations included) ranging from peak base accelerations of 0.1 g to 1.1 g. For Phase B (retrofitted), the specimen underwent a more extensive protocol of 28 tests (white noise excitations included), reaching a maximum intensity of 1.4 g. For the detailed list of the sequential history please see [26,27]. The experimental data obtained from accelerometers and displacement draw-wires were compared with their numerical counterparts generated by ReplicaXLite. To ensure an accurate correlation, the physical sensors were mapped to specific nodes in the Finite Element Model (FEM). The top accelerometer Acc4 results are compared with Node 11 while Acc10 is mapped to the results of Node 18. The top draw-wire (W2) is compared with the numerical Node 11 while the bottom base draw-wire (W4) is compared with the numerical Node 23. The comparative results demonstrate the model’s performance across the respective loading protocols. For Phase A, the acceleration time-histories are depicted in Figure 16, and the displacement time-histories are shown in Figure 17 for the earthquake excitations (white noise excitations were also analyzed but are excluded from this presentation). Similarly, the results for Phase B are presented in Figure 18 for acceleration and in Figure 19 for displacement, covering the extended intensity range for selected earthquake excitations (intermediate additional earthquake excitations as well as white noise excitations were also analyzed but are excluded in this presentation). The quantitative comparison of the results (Pearson and envelope correlation, peak error, NRMSE) are presented in

Table 5. Quantitative statistical evaluation of the numerical model against experimental measurements (Acceleration Phase A and B).

			Bottom Base-Beam				Top Mid-Slab
Phase	Test ID	PGA (g)	rp	re	Epeak (%)	NRMSE (%)	rp	re	Epeak (%)	NRMSE (%)
A	ST2	0.1	0.998	0.998	−7.3	0.79	0.861	0.912	−8.5	4.99
A	ST4	0.2	0.999	0.999	−6.9	0.72	0.821	0.924	−7.3	5.4
A	ST6	0.5	0.999	0.999	−7.2	0.75	0.814	0.896	−7.3	5.49
A	ST8	0.8	0.997	0.999	−7.4	0.81	0.803	0.894	−8.6	5.94
A	ST10	1.1	0.998	0.999	−7.3	0.75	0.814	0.861	−7.6	6.26
B	ST4	0.1	0.999	0.999	−7.8	0.82	0.898	0.956	−9.0	4.24
B	ST11	0.5	0.998	0.999	−7.6	0.83	0.862	0.959	−6.8	5.29
B	ST17	0.8	0.999	0.999	−7.0	0.75	0.767	0.905	−6.2	7.14
B	ST19	1.1	0.999	0.999	−7.2	0.79	0.844	0.894	−6.5	6.95
B	ST25	1.4	0.943	0.947	−8.0	3.72	0.807	0.910	−7.4	7.5

$r_p$ = Pearson Correlation Coefficient, $r_e$ = Envelope Correlation Coefficient, $E_{peak}\left(\mathrm{\%}\right)$ = Maximum Peak Error (%), NRMSE (%) = Normalized Root Mean Square Error (%).

and

Table 6. Quantitative statistical evaluation of the numerical model against experimental measurements (Displacement Phase A and B).

			Bottom Base-Beam				Top Mid-Slab
Phase	Test ID	PGA (g)	rp	re	Epeak (%)	NRMSE (%)	rp	re	Epeak (%)	NRMSE (%)
A	ST2	0.1	0.998	0.998	7.5	1.15	0.978	0.987	−8.1	2.29
A	ST4	0.2	0.999	0.999	6.8	0.77	0.979	0.990	−12.4	2.53
A	ST6	0.5	0.999	0.999	6.1	0.86	0.972	0.984	−7.3	2.64
A	ST8	0.8	0.999	0.999	7.9	0.95	0.974	0.983	−6.1	2.55
A	ST10	1.1	0.997	0.999	6.8	1.08	0.961	0.973	−4.3	3.14
B	ST4	0.1	0.998	0.999	6.1	1.00	0.653	0.968	−8.9	7.89
B	ST11	0.5	0.998	0.999	−0.9	0.69	0.976	0.985	−6.3	2.29
B	ST17	0.8	0.998	0.999	1.8	0.63	0.962	0.976	−13.8	3.83
B	ST19	1.1	0.997	0.998	1.1	0.89	0.951	0.964	−7.1	3.87
B	ST25	1.4	0.964	0.977	8.8	2.66	0.846	0.914	−13.9	6.32

$r_p$ = Pearson Correlation Coefficient, $r_e$ = Envelope Correlation Coefficient, $E_{peak}\left(\mathrm{\%}\right)$ = Maximum Peak Error (%), NRMSE (%) = Normalized Root Mean Square Error (%).

.

The quantitative comparison between numerical predictions and experimental records confirms the high fidelity of the proposed model across varying seismic intensities. As summarized in Table 5, the simulation exhibits exceptional accuracy at the base level, where acceleration Pearson correlation coefficients ($r_p$) consistently approach 0.998 and Normalized Root Mean Square Errors (NRMSE) remain below 1.0% for the majority of test cases. This indicates that the input ground motions and boundary conditions were replicated with high precision. Even at the upper structural levels, where nonlinear accumulation is most pronounced, the model maintains robust performance. For instance, during the high-intensity Phase A tests (0.5 g to 1.1 g), the top-slab displacement correlations remain above 0.96 (Table 6), while the global error (NRMSE) for top-slab acceleration stabilizes between 5.4% and 6.3%. These metrics demonstrate that the numerical framework successfully captures the fundamental frequency and global stiffness degradation of the system, even as the structure undergoes significant dynamic excitation.

A distinct trend is observed regarding peak amplitude prediction, highlighting a trade-off between acceleration and displacement accuracy. The numerical model tends to under-predict peak accelerations at the top slab, with peak errors ($E_{peak}$) generally ranging between 6.2% and 9.0% across Phase A and Phase B. This suggests that localized high-frequency amplification effects in the physical specimen are slightly overdamped in the numerical environment. Conversely, regarding displacement at the bottom base-beam (Table 6), the model exhibits varying degrees of deviation; Phase A shows consistent peak errors between 6.1% and 7.9%, while Phase B shows a wider range from −0.9% to 8.8%. The most significant deviation occurs under the extreme loading of Phase B (ST25, 1.4 g), where the combination of material damage and nonlinear geometric effects results in a maximum top-slab acceleration NRMSE of 7.5% and a bottom displacement peak error of 8.8%. Despite these deviations at higher intensities, the correlation coefficients remain acceptable ($r_p$ > 0.80 for ST25), confirming that the model remains numerically stable and predictive even under severe seismic loading conditions.

5. Discussion

The results presented in the previous section demonstrate the efficacy of ReplicaXLite in bridging the gap between high-fidelity finite element modeling and experimental reality. By utilizing the proposed Structural API, the numerical representation of the 1:3 scaled reinforced concrete frame was successfully generated, analyzed, and correlated with shake table data for both the as-built (Phase A) and retrofitted (Phase B) configurations.

The comparison of acceleration time histories (Figure 15 and Figure 16) reveals a strong agreement between the numerical model and experimental records. In Phase A, the toolkit successfully captured the stiffness contribution of the unreinforced masonry infills using the implemented macro-modeling approach adapted from [29]. The software’s ability to track peak accelerations from low intensities (0.1 g) up to near-collapse states (1.4 g) suggests that the underlying fiber-section generation and material wrappers correctly translate user inputs into the OpenSeesPy solver. Similarly, the displacement histories (Figure 17 and Figure 18) show that the model accurately predicts the period elongation associated with cumulative damage.

Since the current work serves as a wrapper around the core OpenSees solver, previously published sensitivity guidelines are applicable [30,31,32]. Regarding the mesh, functionality is divided into two main parameters. First, for the fiber cross-section meshing, the automatic mesh algorithm provided by opstool was found to offer an optimal balance between performance and quality. Second, regarding integration points, numerous investigations were conducted using two to five points. It was observed that using two points failed most of the time due to excessive integration iterations. Using three points passed all stages of Phase A but could not properly capture the transition to Phase B, failing after 30% of the loading. While four points reached 80% of the loading, convergence difficulties were encountered thereafter. Ultimately, five points provided the most reliable integration; with minimal changes to integration strategies, the model successfully completed both experimental phases.

A significant challenge in this study was the numerical integration of the “Greenery” retrofit—specifically the interaction between the basalt fiber ropes, PUFJ seismic joints, FRPU jackets and the added mass of the vertical living walls. The results in Phase B confirm that ReplicaXLite’s object-oriented architecture allows for complex sequential modifications. The “forced user-released” state described in the methodology enabled the modification of mass and element properties (simulating the installation of planters and jackets) without losing the damage history from previous excitation steps.

This capability is critical for Digital Twin applications where the model must evolve alongside the physical structure. Therefore, it should be noted that the analytical model and the entire time–history of 39 sequential excitations were ordered within the ReplicaXLite hybrid platform in a single run, seamlessly taking into account variations among different construction and renovation steps (stages or phases).

While the validation was successful for frame-based structures with infills, further testing is required for continuum elements (shells and solids) in complex 3D geometries. Additionally, while the system supports “near real-time” monitoring, the latency introduced by the Python-based visualization wrapper (PyVista) increases with model size. Performance benchmarks (see Figure 20) indicate that smooth rendering (≥30 FPS) is maintained for typical laboratory specimens comprising up to 2000–2500 elements (lines). However, the frame rate gradually declines for larger models, dropping to a minimum practical threshold of 5 FPS at approximately 10,000 lines and 3600 nodes.

Consequently, future development may focus on optimizing the rendering pipeline and expanding the library of pre-defined retrofit materials to further democratize advanced seismic analysis.

6. Conclusions

This study introduced ReplicaXLite, an open-source finite element toolkit designed to streamline the creation, analysis and monitoring of 3D structural models. Addressing the gap between solver capabilities (OpenSeesPy) and visual pre/post-processing (opstool), the proposed framework offers an alternative unified environment for researchers and engineers. Key findings regarding the development and validation of the platform include:

• The toolkit successfully integrates four distinct APIs (Structural, Sensors, Units, and DataValidation) into a single GUI/CLI hybrid environment. This allows users to transition seamlessly from raw sensor data processing to complex nonlinear history analysis without external software dependencies.
• The numerical models generated by ReplicaXLite demonstrated exceptional accuracy when validated against extensive shake table tests of a 1:3 scaled reinforced concrete building. The platform successfully reproduced responses across varying sequential seismic intensities (0.1 g to 1.4 g) in a one-run mode. Key findings from this comparison include:

  ○

  Base-Level Precision: The model captured input ground motions and boundary conditions with exceptional accuracy, achieving Pearson correlation coefficients ($r_p$) predominantly at or above 0.99 for the bottom base-beam. Normalized Root Mean Square Errors (NRMSE) remained consistently below 1.2% for most test cases, only peaking at 3.72% for acceleration and 2.66% for displacement during the final, extreme 1.4 g near-collapse excitation (ST25).

  ○

  Global Response and Damage Tracking: At upper structural levels, the software successfully captured the fundamental frequency shifts, period elongation and global stiffness degradation of the system. Top mid-slab displacement Pearson correlations ($r_p$) remained robustly above 0.96 for Phase A. In Phase B, despite accumulated structural damage causing some variance in Pearson correlations ($r_p$) ranging from 0.653 to 0.976, the envelope correlations ($r_e$) remained highly accurate, consistently staying above 0.91. Meanwhile, top-slab acceleration NRMSE showed good stability across both testing phases combined, ranging from 4.24% to 7.5%.

  ○

  Peak Amplitude Prediction: While global behavioral tracking was highly accurate, the model exhibited a consistent tendency to under-predict peak top-slab accelerations, with peak errors ($E_{peak}$) strictly constrained between −6.2% and −9.0%. This indicates that localized high-frequency amplification effects were slightly overdamped in the numerical environment. Similarly, top mid-slab peak displacements were also under-predicted, with peak errors ranging between −4.3% and −13.9%, reaching their maximum deviation during the extreme 1.4 g near-collapse excitation.

• The architecture supports “forced user-released” sequential analysis, where model properties (mass, stiffness and topology) can be modified mid-simulation. This was effectively demonstrated in the simulation of Phase B, where the model was “retrofitted” digitally (adding vertical living walls, basalt fiber ropes and polyurethane joints) to match physical interventions without losing the damage history accumulated from previous excitation steps.
• To properly simulate the entire timeline of 39 sequential dynamic excitations without convergence failure, it was found that an integration scheme utilizing five integration points provided the optimal numerical stability for fiber elements, bridging the transition from the “as-built” Phase A damage state to the highly nonlinear Phase B performance.

ReplicaXLite is available as an open-source repository, encouraging community contribution to further expand its capabilities for the broader structural engineering community (such as complex 3D geometries with shells and solids, etc.).