OpenSeesPy: Python library for the OpenSees ﬁnite element framework

OpenSees, an open source finite element software framework, has been used broadly in the earthquake engineering community for simulating the seismic response of structural and geotechnical systems. The framework allows users to perform finite element analysis with a scripting language and for developers to create both serial and parallel finite element computer applications as interpreters. For the last 15 years, Tcl has been the primary scripting language to which the model building and analysis modules of OpenSees are linked. To provide users with different scripting language options, particularly Python, the OpenSees interpreter interface was refactored to provide multi-interpreter capabilities. This refactoring, resulting in the creation of OpenSeesPy as a Python module, is accomplished through an abstract interface for interpreter calls with concrete implementations for different scripting languages. Through this approach, users are able to develop applications that utilize the unique features of several scripting languages while taking advantage of advanced finite element analysis models and algorithms. © 2017 The Authors. Published by Elsevier B


Motivation and significance
Simulation plays a critical role in the design and assessment of civil infrastructure to resist natural hazards such as earthquakes and tsunamis. While simplified approaches can be used for preliminary analyses, the results are often conservative and can be costly for design and retrofit. As a result, design codes allow engineers to develop more economical solutions that satisfy performance * Corresponding author. objectives ranging from immediate occupancy to life safety. Simulation helps achieve these solutions in engineering practice and also quantify probabilities of exceeding limit states, e.g., using stochastic methods that consider the variability of system properties and external loading.
Developing new simulation models requires a flexible software framework where developers can build off of existing, interchangeable modules. A fully functional finite element analysis software, OpenSees, the Open System for Earthquake Engineering Simulation, was created in the late 1990s as the simulation platform for the Pacific Earthquake Engineering Research (PEER) Center. The OpenSees framework combines state of the art finite  Although OpenSees also has extensions to Graphic User Interfaces (GUIs), such as BuildingTcl and OpenSees Navigator, they typically constrain the user to a particular type of structure and/or analysis [1]. To allow users to take advantage of programming constructs such as conditionals, iterations, and procedures, OpenSees extends the interpreter of Tcl with commands for model building and analysis. While Tcl is very flexible and has many strengths in string processing, it is not well-suited to scientific computing applications. Tcl's use of strings as the only native data type and the resulting cumbersome syntax for mathematical expressions create a steep learning curve for users of OpenSees, many of whom learned MATLAB or Python as undergraduate engineering students.
To remove the limitations of a single scripting language and to permit a wide range of future scripting languages, this paper presents a new interface for the OpenSees framework, the DL_Interpreter class to include multiple interpreters making OpenSees accessible to a broader range of users. In addition, users of OpenSees will be able to utilize functionality from different scripting languages, functionality that is not available in Tcl. The focus herein is on OpenSeesPy, an implementation of the Python interpreter for use with OpenSees; however, the underlying framework is general and can easily accommodate other scripting languages such as Ruby, Julia, and R. The interpreter-independent functions in the OpenSees core and their interaction with the new DL_Interpreter class are described. An example application of a Monte Carlo simulation of a nonlinear truss structure highlights the multi-interpreter interface. The paper concludes with an assessment of the impact of the use of OpenSees.

Software description
The core functionality of OpenSees, including state-of-the-art finite element models and solution algorithms for nonlinear dynamic analysis of structural and geotechnical systems, is described in [2]. In addition to its capabilities for earthquake engineering simulation, OpenSees has been extended for parameter updating and sensitivity analysis [3], fire simulation [4], and fluid-structure interaction [5]. With a wide range of finite element simulation capabilities, the extension of OpenSees with an interface for new interpreters allows users to take advantage of several libraries and packages in developing specialized applications.

Software architecture
To analyze a structural or geotechnical system in OpenSees, a ModelBuilder object populates the Domain with the node, element, load, and constraint objects necessary to build a finite element model of the system and Recorder objects to record the analysis results [2,6], as shown in Fig. 1. An Analysis object computes the state of the finite element model for a particular type of analysis, e.g., static, dynamic, eigenvalue, etc., using interchangeable solution algorithms, linear equation solvers, constraint handlers, and time integration methods.
Users of OpenSees write scripts that invoke an instance of the ModelBuilder class to create the finite element model, e.g., the TclModelBuilder class extends the Tcl scripting language with a node command that creates a Node object from user input by calling functions in the Tcl API [7], such as Tcl_GetInt, then adds the Node object to the Domain. To link OpenSees with Python, or any other scripting language, much of this code for reading input, creating finite element domain objects, performing analyses, and recording results would need to be duplicated. To avoid such code duplication, the ModelBuilder object is replaced by a core, interpreter-independent OpenSees API that populates the domain and performs analyses, as shown in Fig. 2.

Software functionalities
Multi-interpreter functionality for OpenSees is provided through the DL_Interpreter interface shown at the top of Fig. 2, which defines eight basic input/output (IO) functions for obtaining integer, floating point, and string inputs. Each scripting language will define its own interpreter class that implements the DL_Interpreter interface, e.g. TclInterpreter and Python-Interpreter, for the eight IO functions. Each implementation deals with language related operations, such as initializing the language, printing information, setting up environmental variables, loading startup modules and files, and extending functions or commands.
Since language related codes could be cumbersome, a wrapper class is defined within an interpreter class to share the responsibility of wrapping OpenSees core APIs. Therefore, the core APIs only contain pure OpenSees code for populating the model domain, running analyses, and manipulating internal objects, so that these operations work identically across all interpreter languages. If an IO operation is required, a core API will call the OpenSees IO APIs, e.g., OPS_GetIntInput, which are also interpreter-independent and will make polymorphic calls to the eight basic IO functions through the DL_Interpreter interface. With this design, the core OpenSees APIs are completely separated from the interpreter and the effort to add a new interpreter is minimized.

Illustrative examples
The power of OpenSees is to create models, execute analyses, and record results dynamically through scripting. The simple material nonlinear truss structure shown in Fig. 3 is created and analyzed. The intent here is not to show a full structural analysis, but rather to highlight the underlying code that enables the use of OpenSees through multiple interpreters.

Model building
In the truss model shown in Fig. 3, nodes are numbered from one through four and elements one through three. Snippets of Tcl and Python code to create the truss model are shown in Fig. 4. Although the two languages have very different syntax and formats for function calling, the function input parameters are always listed serially, which is true for almost all general purpose and scientific languages.
As previously described, interpreter classes implement the eight basic IO functions through the DL_Interpreter interface, which read and record in the same order internally for all languages. For example, the OPS_GetDoubleInput function calls the getDouble() virtual method to read the next input parameter as a floating point value, e.g. material elastic modulus, E, in Fig. 4. The

Simulation results
Since the same core API functions are called, separate interpreters should create finite element models that give the same simulation results. For the truss example, the external loads are applied to the structure in multiple steps of a static analysis. Both interpreters report the horizontal displacement of node 4 as u 4 = 1.510431 in at the peak load of 160 kip.
To demonstrate a reliability analysis, three structural parameters, truss section area A, material yield stress σ y , and the horizontal load P x , are defined and random numbers are generated from normal distribution for the parameters with mean values shown in Fig. 4. The standard deviations are 0.5 in 2 , 2.0 ksi, and 10.0 kip for A, σ y , and P x , respectively. Monte Carlo simulation is then run and the probability of failure of the truss structure is calculated as shown in Fig. 9. Failure of the structure is defined in terms of the horizontal displacement of node 4 using the following limit state function    Due to differences in their random number generators, the Python and Tcl interpreters lead to probabilities of failure of P f = 0.1577 and 0.1589, respectively, after 10,000 random trials. This means the horizontal displacement of the truss has a nearly 16% chance of exceeding the prescribed limit considering the random variable distributions of each parameter. Realistic structures are more complex; however, this example conveys the essential ideas of the multiple interpreter capability.

Impact
From its early use by researchers in PEER, OpenSees has grown to a large international user base. In 2016, there were over 1.5 million page views at its website http://opensees.berkeley.edu. OpenSees has been used as the primary simulation tool for numerous graduate theses in the United States and at major universities worldwide. The applications of OpenSees are cross platform (Windows, Linux, and OS X), range from simple serial applications through complicated parallel applications, and are widely used on a range of computing resources, including desktops, Amazon clusters, and high performance computing platforms. The finite element modules of OpenSees can also serve as the analysis engine for developing fragility functions that quantify the resilience of connected systems of civil infrastructure to a wide variety of natural hazards. To address research questions around community resilience, the IN-CORE multi-hazard decision framework [8] uses Python as its glue language for linking structural fragilities generated by OpenSees to investment decisions for bridges, buildings, and electrical transmission systems.
With its extension to Python, users of OpenSees gain access to the plotting library Matplotlib, numerical libraries Numpy and Scipy, interactive server Jupyter, 3-D visualization library Mayavi, statistics library pandas, web development library Flask, among others. In addition, OpenSees can now use the Visualization Toolkit (VTK), an open source, permissively licensed, cross-platform toolkit for scientific data processing, visualization, and data analysis [9], as one of its post-processing tools.

Conclusions
The multiple interpreter capability of OpenSees reflects its evolution to keep pace with new scripting languages from the software computing community. New interpreters can be added quickly to take advantage of libraries and modules from the scripting languages. With the development of the OpenSees core APIs, which are separate from the interpreters, the finite element modules of OpenSees can be re-structured to utilize new advances from the engineering mechanics and numerical methods communities at the source code level. As an open source framework, it is expected that this capability will keep OpenSees relevant within a large user base and with advances on both fronts of scripting languages and nonlinear finite element analysis.