StrucPy.RCFA- Object-Oriented Python Package for Structural Analysis of Reinforced Concrete Frames

2.1. Theoretical Background

The StrucPy.RCFA package adopts the direct stiffness method to perform the structural analysis of RC members/frames where every structural element is represented by its 12 × 12 stiffness matrix [k] in the local coordinate system. The direct stiffness method is grounded on three principles: Equilibrium, Compatibility, and Constitutive Behaviour [41]. Each structural element is represented by its 12 × 12 stiffness matrix [k] in the local coordinate system [42], which quantifies its resistance to deformation. Every local stiffness matrix in the local coordinate system is then transformed into the global coordinate system using the transformation matrix [T] [43]. By assembling these matrices, a global stiffness matrix [K] for the entire structure is obtained by recognizing the shared nodal degrees of freedom between elements [44]. The unknown displacements are found by invoking matrix algebra, particularly matrix inversion techniques [45]. With the known forces and the inverse of the appropriate submatrix of [K], the nodal displacements are determined. With the displacements known, the elemental force-displacement relationship is used to retrieve internal forces for each member considering the load distribution within the structure. The finite difference method (FDM) is used in this package to calculate the displacements at various points within the RC elements. It operates by effectively discretizing the continuous domain into a series of nodal points [46]. The differential equation is then transformed into algebraic equations, which are solved simultaneously to attain the solution [47].

RCFA module performs static seismic analysis of RC frames as per IS 1893:2016 [48]. The analysis is performed using the elastic approach, and the structure’s response is evaluated under the action of the design earthquake by applying the equivalent lateral forces. The equivalent lateral load distribution is determined based on the seismic zone factor, importance factor, and response reduction factor specified in the code. The calculated forces are then distributed along the height of the structure using appropriate lateral load distribution mechanisms as suggested by the code. The structure’s dynamic characteristics, such as time periods, seismic shear, and story drift, are obtained through analysis. The stability index Q is a parameter used to quantify the relative lateral stiffness of a column and determine its behaviour as either a sway or non-sway column. The calculation of stability index Q is carried out as per annex E of IS456:2000 [49]. The effective length of the columns is also determined as per IS456 which is based on the work of wood [50]. The calculated stiffness ratio is then used to determine the effective length factor, separately for sway and non-sway frames.

2.2. Architecture

RCFA is an object-oriented module of the ‘StrucPy’ library purely written in Python, that encapsulates reinforced concrete elements/frames into an object. The RCFA module exhibits a sophisticated interaction with a group of other Python libraries, capitalizing on their individual strengths to provide an effective toolkit for the structural analysis of reinforced concrete members/frames. One of the foundational dependencies is ‘numpy’ [51], an essential library in the scientific computing realm. Within RCFA, numpy controls complex matrix manipulations and operations, providing both speed and precision. This numerical efficiency is particularly vital when dealing with large datasets of complex reinforced concrete frames. Another dependency is ‘pandas’ [52], which provide efficient data structures for data manipulation and analysis. RCFA leverages pandas dataframe for structured data storage, enabling easy querying, filtering, and aggregation. The third dependency is ‘plotly’ [53], a versatile graphing library. Through plotly, RCFA offers intuitive and interactive visualizations with features like zooming, panning, and hovering over data points to display additional information. This interactivity enables users to explore data more dynamically and engagingly. Lastly, the ‘ray’ [54] library enhances the scalability and performance of RCFA. Ray provides a framework for parallel and distributed computing. Intensive tasks are distributed across multiple cores, dramatically speeding up computations. In essence, each of these libraries contributes unique capabilities that, when combined, make RCFA a potent tool for structural analysis of reinforced concrete members/frames.

Currently, two Python classes are being used in the module, making it simple to manage and expand. Each of the classes contains several methods, capable of performing various operations. A complete list of classes along with their methods of the RCFA modules is shown in Figure 1. RCF class of RCFA deals uniquely with single load combinations and contains numerous useful methods capable of collecting specific information from RC member/frame objects. Another class RCFenv of RCFA handles multiple load combinations and generates an envelope for load combinations. All the methods of RCF are accessible from RCFenv to retrieve complete data related to any specific load combination using ray actors.

Figure 1

RCFA’s classes accept model input data as instance variables in the form of values, boolean operators, and dataframes. In the context of RC frames where input parameters can vary to thousands, a dataframe is utilized to feed various parameters and properties of the frame in an organized manner. RCFA requires some mandatory model parameters to carry out structural analysis like frame nodal details, member details, and boundary conditions. These mandatory arguments are only accepted in the form of a dataframe. The dataframes consist of columns representing various detail of instance variables. Each row corresponds to a specific member of the frame with a unique identification (ID) number. The IDs of all the members and nodes should be a natural unique number assigned to them as the dataframe’s index. Users can populate the dataframe with relevant data extracted from architectural drawings and other requirements. This approach not only streamlines the input process but also enhances the reusability of data and facilitates easy modification of input parameters. Currently, RCFA offers various input arguments, which are presented in Table 2 along with its data type and utility. The templates of all the dataframe instance variables can be accessed in the repository folder ‘inputfiles’.

2.3. Features

RCFA is a powerful package specifically for the structural analysis of RC members and frames. It is capable of generating visualization for 3D models, deflected shapes in 3D space, shear force diagrams, bending moment diagrams, and deflected shapes of members using various package methods. The module is equipped with automated generation of frames and floors which allows to perform complex structural analysis with very few lines of Python code. Perhaps one of the most promising features of the module is the high level of user control. Users can control every aspect of the model input, model generation, and model data, allowing for great flexibility in terms of usage. Currently, RCFA is capable of handling structural analysis from single beam elements to complex RC frames. A detail of all the module features is presented in Table 3. There are a few limitations to the feature of floor assignment and floor load distribution. Presently, the floor is considered a flexible diaphragm with zero in-plane stiffness, and floor loads are distributed according to the tributary area. Moreover, the floor should be surrounded by beam elements on all four sides to distribute loads efficiently and correctly.

RCFA’s error management capabilities make it very user-friendly and easy for early programmers. RCFA requires a large number of input details for analysis in various formats. Further, some methods of RCFA are required to be called sequentially. To address these challenges and to assist users, the RCFA library has been equipped with various exceptions. Input validation is quite vigorous as it prevents incorrect or malicious data from causing problems. RCFA offers an extensive range of input validation, from data types to dataframes column arrangement details; ensuring that the input adheres to the expected formats and columns of the dataframe. For instance, RCFA.RCF.member_details raises an exception if the input value is not a dataframe as shown in Figure 2(a). Similarly, if the IDs of members and nodes are incorrect it raises an exception as presented in Figure 2(b). Columns of the dataframes are positional arguments and cannot be left out. The index of the boundary condition must be a valid node ID as it represents the joint conditions. In order to tackle the correct input of columns and valid IDs, RCFA identifies the invalid IDs and correct order of the columns through raising exceptions as shown in Figure 2(c), (d). To ensure the correct order of methods execution an exception is raised, for example, if the analysis is called before the pre-processing of model data an exception is raised as shown in Figure 2(e).

Figure 2

2.4. Usage

The package’s documentation and GitHub repository include comprehensive examples in its examples section, illustrating the structural analysis of different RC members and frames through the RCFA package. An example is illustrated in Listing 1, dealing with class ‘RCF’ which demonstrates the use of RCF class to perform seismic analysis of a 6-story RC ordinary moment resisting frame (OMRF). The frame is auto-generated and the library repository’s ‘inputfiles’ section contains input files for the given example. In the listing, the model’s input files containing the information for auto frame generation, seismic definition, and load combination are imported in lines 3–5. An object representing the RC model with all the model input information is created using the RCF class in line 6. The instance variable ‘autoflooring’ as True generates floors automatically on every story of the RC frame during the pre-processing. The method ‘preP’ performs pre-processing to arrange and acquire member’s information in line 7. The model can also be edited as per the user requirements using the method ‘changeFrame’ as shown in lines 12–13. In this example, a few members are deleted from the initial model, and all members are assigned rectangular cross-sections in lines 10–11. Further, a uniformly distributed load of 10 kN/m is applied to all the beam members in the direction of gravity (line 12). The method ‘changeFL’ allows the user to the change floor’s thickness and load on all the stories of the frame at once. In this example, the floors are edited in line 14 with a thickness of 100 mm and a uniformly distributed dead load of 5 kN/m², and a live load of 3 kN/m² is applied to every floor. Uniformly distributed loads on members and all floor loads except the live load are considered dead loads in this package. Structural analysis of the generated RC frame is performed in line 15 using the method ‘RCanalysis’. Further, various other information can be extracted from the model after performing the structural analysis as shown in lines 16–19.

Listing 1.

The variable ‘reactions’ represents the base joint forces of the RC frame structure, while the variable ‘ndisp’ contains the joint displacements of the frame. The variation of shear forces and bending moments along the length of the member is obtained in the variable ‘sfbmd’. The property of the material used in the structural analysis is obtained through the method ‘Mproperties’. The initial RC model and edited model are presented in Figure 3. All the generated plots, interactive visualizations, and output of the presented example is available in the package’s repository. Complete examples along with all interactive visualization and plots, and output in Excel are available in the repository. The presented example can be executed on any integrated development environment (IDE) for Python, but Jupiter Notebook is preferred for better visualization. The model can be visualized at any time after pre-processing in order to check the nodes, members, and floor IDs. The visualization of the model allows the selection of single components interactively for better understanding. The initially generated RC model using ‘framegen’ and the edited model used in the example are presented in Figure 3. The initial frame was generated automatically, and then the members and loads of the generated frame were edited using the method ‘changeFrame’.

Figure 3

2.5. Validation

This section of the paper presents and validates the results obtained from the StrucPy.RCFA package. It demonstrates the accuracy and reliability of the RCFA for structural analysis and provides insights into the compatibility of the results with industry-standard software like STAAD PRO connect edition, a widely used commercial structural analysis software. The RCFA module of the StrucPy library and STAAD PRO are employed to analyze the structure presented in the example of this paper. All the details of the model such as the structure’s geometry, material properties, loading conditions, boundary conditions, and seismic definition were kept similar. Table 4 shows the comparison of the seismic calculation by RCFA and STAAD Pro respectively. The values are found to be the same and the only difference is that the RCFA package does not round off the values until the final analysis is performed while STAAD Pro rounds off all the values as evaluated.

The comparison of the seismic story shear by RCFA and STAAD Pro is presented in Table 5. In comparing the results of seismic calculations and seismic story shear between the RCFA Python package and STAAD Pro, it is observed that the values are perfectly colinear to each other. The RCFA package does not round off the values until the final analysis is performed. This approach maintains the precision of the calculations throughout the analysis, ensuring that no significant figures are lost prematurely. On the other hand, STAAD Pro rounds off all the values as they are evaluated, which can lead to minor differences in the final results compared to the RCFA package.

This distinction in rounding off values has little impact on the overall accuracy of the RC-framed structure. The RCFA package’s approach of preserving precision until the final analysis results in a slight variation in story forces and displacement in the applied seismic direction compared to STAAD Pro. The difference in the values of the results is classified as an error. To quantify this error, the base reactions, maximum member force, nodal displacements, and deflection in local coordinates were calculated for all relevant nodes and members. The chart representing the distribution and variation of errors is depicted in Figures 4 and 5 for forces and displacements respectively. Despite the differences, the maximum error identified is 4 kN in the y-direction force, with an overall percentage error below 0.01% in Figure 4. This suggests that while there are discrepancies between the RCFA packages and STAAD PRO, they are relatively minor in the context of the structural analysis, and the overall accuracy of the RC-framed structure is not significantly affected. Additionally, the maximum difference in nodal displacement was found to be 3.6 mm in the direction of the seismic force in Figure 5. These discrepancies are attributed to the rounding off of values in the calculation process. However, it is noted that these differences are minimal when compared to the original values and have almost zero effect on the behaviour of the RC frame. Overall visualization of errors in the figures provides a clear understanding of how the errors are distributed throughout the structure and helps in identifying patterns. Overall, while there are differences in the results between the RCFA package and STAAD Pro due to their respective approaches, these variances have negligible effects on the structural behaviour of the RC frame.

Figure 4

Figure 5

RCFA is also capable of generating the shear force and the bending moment diagram in local and global coordinate systems for all the members of the frames. RCFA can generate shear force and bending moment diagrams in all three directions. Figure 6 showcases the shear force diagram in the y-direction and the bending moment diagram in the z-direction, as generated by RCFA for member 47 from a given example. It is noted that these diagrams closely resemble those generated by STAAD Pro, displaying an almost negligible variation. These diagrams are produced utilizing the Plotly library, which allows for saving in various formats offered by Plotly and renders them interactive when saved with an HTML extension. In addition to the graphical representation, RCFA furnishes data regarding the variation of shear force and bending moment values along the length of the member, with a precision of 0.01 m. This feature provides students and researchers with detailed insights into structural forces, aiding in the efficient analysis and design of reinforced concrete elements and frames.

Figure 6

RCFA offers the functionality to generate the deflected shape of frame members in both local and global coordinate systems, providing engineers with comprehensive insights into structural behaviour. Figure 7 illustrates the deflected shape in the x and y directions for member 47 in the global coordinate system. Notably, these diagrams closely resemble those produced by STAAD Pro, exhibiting minimal variation. RCFA’s capability extends beyond just plotting deflected shapes and diagrams; it also offers access to precise data on deflection in every direction for all members in local and global coordinate systems with the least count of 0.01 m along the length of the members. Furthermore, this deflection data provides engineers with the necessary information to ensure that structural elements meet safety and performance requirements.

Figure 7

2.6. Scalability

Scalability analysis is a crucial aspect of any software package, especially in the field of structural analysis. It helps in determining, how well a software package performs as the size of the problem increases and how sensitive results are to the changes in large-scale RC models. In the case of the RCFA package, scalability is evaluated by analyzing four different structures: a single RC member, an 8-member RC frame, a 64-member RC frame, and a 1070-member RC frame. The error, along with computational time, was assessed for each structure, and the variation in the error was plotted in Figure 8 to evaluate the sensitivity to scalability of the RCFA package. It is noticed that the error variation is below 0.2, which is very low with the scalability of the RC frame structure. The RCFA package is found to exhibit low sensitivity with the increasing complexity of the RC frame structure.

Figure 8

For the single RC member, the analysis serves as a baseline for comparison with more complex structures. This simple structure allows for a quick evaluation of the RCFA package’s performance. The computational time for the structural analysis of a single member was found to be 5.022 seconds. The error and computational time are expected to increase compared to the single member, but the rate of increase is a critical factor in determining scalability. If the error and computational time increase significantly faster than the size of the structure, it could indicate a scalability issue. However, if the increase is relatively consistent with the increase in structure size, it suggests good scalability. The RC frame with 8 members was analyzed by RCFA in 5.36 seconds, the computational time was similar to that of a single member with very little error in the result. Similarly, RCFA completed the structural analysis of the RC frame with 64 members in 9.92 seconds with no increase in error. Next, the 1070-member RC frame provides a more challenging test for the RCFA package’s scalability. This structure is much larger and more complex than the previous ones, the number of interactions and calculations also increases exponentially. The RCFA package efficiently handles these calculations to maintain a reasonable computational time of 84.26 seconds while minimizing the errors. In conclusion, this section of the paper ensures that the RCFA package can reliably analyze structures of all sizes and provide accurate results for engineering analysis.

2.7. Technical Constraints and Extendibility

The StrucPy package, which currently focuses on structural analysis of reinforced concrete framed structures via the RCFA module, has few technical constraints that shape its current capabilities and future development. These constraints are crucial for users to understand when considering its application in their projects. Firstly, StrucPy.RCFA’s current design assumes that floors are surrounded by beams on all sides. This design constraint is essential for effectively transferring loads to the columns and ensuring structural stability. However, it limits the applicability of the package to structures that adhere to this specific framing configuration. Future versions may address this constraint to support a wider range of structural configurations such as cantilever floors. Secondly, StrucPy lacks certain analysis features such as P-delta analysis, dynamic seismic analysis, and wind load considerations. These features can boost the capability for assessing the behaviour of structures under various other loading conditions. While these capabilities are absent in the current version, it is being actively worked on to incorporate them in the next version. Despite these constraints, StrucPy’s modular and object-oriented design makes it relatively easy to extend and modify. This flexibility enables users to customize the package to suit their specific needs and integrate it with other Python libraries seamlessly. Furthermore, the active development and planned enhancements indicate that StrucPy is continuously improving to meet the needs of structural engineers, students, and researchers.

The object-oriented nature of the StrucPy.RCFA module offers a flexible and modular approach to structural analysis, making it easier to extend or modify its functionality. The modular structure of the RCFA allows you to modify existing classes or methods to improve performance, accuracy, or usability. For instance, users can optimize algorithms for better computational efficiency or enhance error handling to improve the robustness of the package. Currently, RCFA allows input to be very flexible to consider various loading and support conditions. The user can further extend the RCFA module by adding new classes or methods to handle additional types of structural elements and post-processing functionalities. Further, the RCFA module can be easily integrated with other Python libraries to leverage their capabilities. StrucPy.RCFA has been successfully used to retrieve beam force data and to collaborate with package PyRCD for the design optimization of RC beam [55].