The following example is used to illustrate the way to configure the OpenSees SubStructure for multi-platform simulations.

The example is a two-dimensional one-story one-bay steel frame with a single concentric buckling-restrained brace (BRB) to resist lateral loading due to the earthquake excitation. The columns are simply supported at their base and the beam is connected to the columns using simple connections without flexural rigidity. Both columns are 254x254x8.0 HSS members of Class C 350W structural steel. The beam element can be assumed to be an axially rigid element. The core of the BRB consists of a 160mm x 6.4mm steel plate of 300W structural steel. The whole system is supported by a raft foundation founded on dense soil where the soil settlements are negligible. The seismic weight of the system is 2000 KN (equivalent to a seismic mass of 204 tons) and is lumped at the first story.

The structure is decomposed into one OpenSees integration model and one OpenSees substructure model. Specifically, the beam and columns are modelled with a truss element and two elasticBeam elements, respectively, in the integration model. The substructure model only includes the BRB modelled with truss element. Communication between the two models is endabled through the SubStructure elements in the OpenSees integration and substructure models.

OpenSees Integration Model (SubStructure element)¶

Compared with the standalone OpenSees model where the complete frame structure with the BRB is modelled, the OpenSees integration model is the same as the standalone model except that the truss element for the BRB is replaced with the SubStructure element as shown below:

• Standalone model

  puts "Define Elements";
    element corotTruss 1 1 4 1; # BRB defined as a truss element
    element elasticBeamColumn 2 1 3 $Ac $E $Ic $TFrame; # Column Element Between Nodes 1 & 3
    element elasticBeamColumn 3 2 4 $Ac $E $Ic $TFrame; # Column Element Between Nodes 2 & 4
    element corotTruss 4 3 4 2; # Beam Element Defined
  

• Integration model

  puts "Define Elements";
    element SubStructure 1 -file Structfile.txt -Kinit Kinit.txt
    element elasticBeamColumn 2 1 3 $Ac $E $Ic $TFrame; # Column Element Between Nodes 1 & 3
    element elasticBeamColumn 3 2 4 $Ac $E $Ic $TFrame; # Column Element Between Nodes 2 & 4
    element corotTruss 4 3 4 2; # Beam Element Defined
  

The command to define the SubStructure element is

      element SubStructure $eleTag -file $filename1 -Kinit $filename2

where

• eleTag - unique element object tag
• filename1 - configuration file
• filename2 - optional, file containing initial stiffness matrix of the elements modelled in the substructure module, e.g. the BRB element in this example

Configuration file of SubStructure¶

The configuration file (Structfile.txt) of the example structure is shown below

#Configuration file for SubStructure element
# Ttype = 1 - integration module
#         2 - substructure module
Ttype = 1

# Port number
Port = 8090

# Remote server address
IP = 127.0.0.1

# Number of dimensions
NumDim = 2

# Controlled node tag
NumNode = 2
1 4

# Effective interface DOFs in control point.  
# Note: 1.The sequence of DOFs should be consistent with sequence of DOFs in the substructure module.
#       2.Use one line per each controlled node.
#       2.For 2D 3DOF model, use DOF 1, 2, 6 (not 1, 2, 3) for x, y, rz DOFs.  
EFF_DOF = 
1 1 0 0 0 0
1 1 0 0 0 0

# Type of the substructure module 
# 1 - OpenSees (default)
# 2 - Zues-NL
# 3 - ABAQUS
# 4 - VecTor2
# 5 - Test equipment (hybrid simulation)
SubType = 1

# Log file
# 1 - no log file
# 2 - log file
CommLog = 2

where

• Ttype - this parameer indicates the type of the module. Set this paramter to 1 and 2 for integration module and substructure module, respectively.
• Port - This parameter defines the port number for communication between the OpenSees integration model and the remote substructure model. Consistent port numbers should be specified in the integration and substructure model. In this example, 8090 is used as the port number.
• IP - This parameter defines the IP address of the machine with the substructure model. In this example, since the integration and substructure models are developed on the same computer, the loopback IP address "127.0.0.1" is used.
• NumDim - This parameter indicates the number of dimensions of the simulation model.
• NumNode - This parameter defines the number of interface nodes for data exchange. Besides, the interface node tags are listed in the line next to the keyword "NumNode = " and separated by space. In this example, there are two interface nodes corresponding to the two nodes of the BRB element, i.e. Node 1 and Node 4.

• EFF_DOF - This parameter is used to indicate the effective degrees of freedom (DOFs) of each interface node specified in NumNode. In this example, the EFF_DOF parameter is followed by two lines that describe the effective DOFs of the two interface nodes. For example, the first line after EFF_DOF corresponds to the first interface node specified in NumNode, i.e., Node 1. Each line includes six indicators that represent the three translational DOFs and three rotational DOFs, respectively, in the global coordinate system of the numerical model. The DOFs are enabled or disabled for communication between the OpenSees integration model and the substructure model by setting the corresponding indicators to 1 or 0. For the BRB element in this example, only the two translational DOFs along the x- and y-axis are enabled to transfer data (i.e. displacement and force). The resultant displacement and force vectors for data exchange are

• SubType - this parameter indicates the type of the connected substructure module through this substructure element.
• CommLog - this parameter is for data logging. If Comm_log=1, a log file with displacement commands and feedback signals at each analysis step will be generated for further analysis. No log file will be generated if Comm_log=0.

Initial stiffness file of SubStructure¶

The stiffness file (Kinit.txt) of the example structure defines the initial stiffness of the BRB element which is a $4\times4 $ matrix as shown below:

22.9621   12.62920  -22.9621  -12.62920  
 12.6292    6.94605  -12.6292   -6.94605  
-22.9621  -12.62920   22.9621   12.62920   
-12.6292   -6.94605   12.6292    6.94605

OpenSees Substructure Model (SubStructure element)¶

In addition to the Truss element to model the BRB, a SubStructure element is included in the OpenSees substructure model to transfer data at the interface nodes as shown below.

puts "Define BRB Element in HS";
element corotTruss 1 1 2 1; # BRB defined as a truss element
element SubStructure 2 -file Substrfile.txt

The command to define the SubStructure element is

element SubStructure $eleTag -file $filename

where

• eleTag - unique element object tag
• filename - configuration file

Configuration file of SubStructure¶

The configuration file (Substrfile.txt) of the example structure is shown below

#Configuration file for substructure element 
# Ttype = 1 - integration module
#         2 - substructure module
Ttype = 2

# Port number
Port = 8090

# Connected node tag
NumNode = 2
1 2

# Number of dimensions
NumDim = 2

# Effective DOFs in control point.  
# Note: 1.The sequence of DOFs should be consistent with sequence of DOFs in UI-SimCor.
#       2.Use one line per each controlled node.
#       2.For 2D 3DOF model, use DOF 1, 2, 6 (not 1, 2, 3) for x, y, rz DOFs.  
EFF_DOF = 
1 1 0 0 0 0
1 1 0 0 0 0

# Penalty number
Penalty = 1e12

# output log file
# 1 - no log file
# 2 - log file in text format
CommLog = 2

The configuration file also includes the parameters Ttype, Port, NumNode, NumDim. EFF_DOF, and CommLog as those defined in the "Structfile.txt" file. Besides, it has a Penalty parameter which defines a penalty factor to impose the received displacement from the integration model on the interface nodes in the substructure model. The penalty value should be large enough to ensure that the interface nodes of both integration and substructure models have consistent displacements. However, a too large value could lead to convergence issues. As a slave program, the OpenSees substructure model runs static analysis based on the displacement commands sent from the integration model. The OpenSees analysis commands for computing the restoring forces of the BRB are illustrated below

# define external load -------------------------------------------------------------
pattern Plain 1 Linear {
   load 1 0. 0. ;                   # node#, FX FY --  superstructure-weight
}
constraints Transformation;         # how it handles boundary conditions
numberer Plain;                     # renumber dof's to minimize band-width (optimization), if you want to
system BandGeneral;                 # how to store and solve the system of equations in the analysis
test NormDispIncr 1.0e-8 100 ;      # determine if convergence has been achieved at the end of an iteration step
algorithm Newton;                   # use Newton's solution algorithm: updates tangent stiffness at every iteration
integrator LoadControl 1;           # determine the next time step for an analysis, # apply gravity in 10 steps
analysis Static;                    # define type of analysis static or transient
set ok [analyze 1000000];           # perform static analysis

The users should refer to the following rules to define the above analysis commands.

• The Plain LoadPattern with zeros forces applied to at least one of the interface nodes. This is because the deformation of the numerical elements in the substructure model is fully controlled by the displacement data sent from the integration model through the network.
• The LoadCotnrol integrator with a load factor increment of 1.0 should be used to apply the received displacement data to the numerical elements in one step.
• Theoretically, the total number of analysis steps defined in the OpenSees substructure model should be consistent with the number of times that the integration model sends the displacement data to the substructure model. However, due to the potential iterations involved in the integration model, the total number of analysis steps is unknown before the simulation. Therefore, a large number of analysis steps (e.g. 1000000 in this example) should be used in the substructure model to cover the possible number of iterations in the integration model.

Run Simulation¶

Upon completion of the above configurations, the simulation can be performed by first running the OpenSees substructure model followed by starting the OpenSees integration model. The multi-platform/hybrid simulation result compared with the standalone/complete OpenSees model is shown below:

                            Example Download
                            The above simulation example can be downloaded from here.