The following example is used to demonstrate the configuration details of the applications, i.e., integration module, NICON-AIO(1DOF version) for hybrid simulations.

The example is a simple two degrees of freedom (DOFs) mass-spring system shown above. The system only experiences motion in the horizontal direction. The masses are free to slide horizontally. Both M1 and M2 are 20.0 kg, while K1 and K2 are 5.0 N/mm. A damping ratio of 2% is assumed for the first and the second mode of the structure. The periods of the structure are calculated as 0.643 seconds and 0.246 seconds for the first and the second modes, respectively. In order to limit the time of the experimental hybrid simulation, Arias intensity time bracketing scheme is used to obtain a portion of the M6C1 earthquake ground motion record during which 15% to 85% of the seismic input energy is accumulated. The main criteria for choosing such duration is to limit the ground motion length. The resulting ground motion, which is included in the example files (M6C1_1.txt) is 2.4 seconds long. A scaling factor of 3.0 is used for the ground motion. This factor is determined such that the displacement of the physical substructure does not exceed the actuator stroke.

The structure is decomposed into one OpenSees integration model with the two masses and the element K2 while the substructure model includes the element K1 that is represented as a spring, as shown below.

OpenSees Integration Model¶

The way to configure the OpenSees integration model for this sample test can be found here.

NICON-AIO (1DOF)¶

The version of the interface program NICON that is used in the current example is developed for one-dimensional problems and is included in the example files. The NICON program is responsible for establishing communication between the OpenSees integration module and the actuator controllers, to ensure that the displacements of the interface nodes, in the numerical model and the physical specimen are synchronized. In essence, in each step, the NICON program will communicate the command displacements to the actuator controller. The actuator controller will then apply the displacement command to the actuator. The load cell will measure the force feedback of the specimen, and the actuator’s linear variable differential transformer (referred to as internal LVDT) will measure the actual actuator's stroke. Typically, an extra displacement sensor like a LVDT (referred to as external LVDT to be distinquished from the internal LVDT) is required to measure the actual deformation of the specimen as it could be different from the actuator's stroke due to the elastic deformation of the testing frame or slackness or gaps at the connections of the test setup, as shown below.

To minimize the difference between the target ($u_t$) and actual specimen's displacement ($u_a$), an error compensation scheme has been implemented in the NICON program. The error compensation scheme utilizes an iterative scheme by updating the displacement command ($u_cmd$) as follows:

$u_{cmd}^{(k+1)} = u_{cmd}^{(k)} + \alpha(u_t - u_{a}^{(k)})$

where the superscript $k$ represents the value at the $k$-th correction/iterative step; $\alpha$ is the gain factor ranging from 0 to 1 to control the correction amount. The iteration process for each analysis step stops whenever one of the following is satisfied:

• The current number of iterations $k$ is equal to the predefined maximum number of iterations for each analysis step;
• $|u_{t}-u_{a}^{(k)}\leqslant\delta|$, where $\delta$ is the user-defined error tolerance.

More details about the error compensation scheme can be found in reference. The force and displacement feedbacks of the specimens are then communicated from the actuator controller to NICON. NICON will send the displacement and force feedback to the OpenSees integration module, and the analysis will proceed to the next step.

The National Instrument hardware is connected to the actuator controller in the test setup. The NI DAQ hardware that is used in the current example is NI USB-6218, as shown below.

It is important to verify that the input/output channels that are used for displacement and force measurements are consistent with the designated physical channels, in NICON configuration file. The ports that are used in the experimental setup are marked as below.

Each port and its use are discussed below:

1. Analog Input 0 (AI0): This is the channel for the measured actuator's stroke
2. Analog Input 1 (AI1): This is the force measurement channel
3. Analog Input 2 (AI2): This is the channel for external LVDT to measure the actual specimen's deformation
4. Analog Output 1 (AOI): This is the actual displacement/stroke command channel

There is a single configuration file (NICON_Config.cfg) to define the parameters requires for the functions implemented in NICON-AIO.

NICON_Config.cfg¶

The key parameters in the configuration file are explained below:

• PortNumber. This parameter should be consistent with the port number defined in the numerical model
• Ramp_ms. This parameter specifies the duration of the ramp stage. (unit: milliseconds)
• Hold_ms. This parameter specifies the duration of the hold stage. (unit: milliseconds)
• a0/a1. They are the scale factors to convert the displacement command to corresponding voltage signal (unit: Volt) based on the formula

$voltage = a_0 + a_1 * u_{t}$

• b0/b1. similar to a0/a1, they are the scale factors to convert the feedback signals to measured stroke values (unit: mm) based on the formula

$u_{f} = b_0 + b_1 * voltage$

• c0/c1. similar to b0/b1, they are the scale factors to convert the feedback singals to measured force values (unit: kN) based on the formula

$F_{f} = c_0 + c_1 * voltage$

• LimitDispMin/LimitDispMax. This parameter defines the minimum/maximum displacement/stroke limit of the actuator (unit: mm)
• LimitDispInc. This parameter defines the maximum displacement increment (unit: mm)
• LimitForcMin/LimitForcMax. This parameter defines the minimum/maximum force limit (unit: kN)
• LimitForcInc. This parameter defines the maximum force increment (unit: kN)
• IOUpdateRate. This parameter specifies the I/O sampling rate (unit: ms)
• MonitorRefreshRate. This parameter specifies the rate for data logging (unit: ms)
• OutputCh. This parameter defines the output channel to impose the target displacement command to the actuator controller. It follows the format of "Device/Channel" where Device indicates the name of the NI DAQ device (e.g., Dev1) and Channel indicates the name of the channel, e.g., AO1.
• InputCh1/InputCh2. Similar to OutputCh, this parameter defines the input channel to receive measured stroke/force feedback from the controller.
• d0/d1. Similar to a0/a1, they are the scale factors to convert the feedback signal to measured specimen's deformation (unit: mm) based on the formula

$u_{a} = d_0 + d_1 * voltage$

• InputCh3. Similar to OutputCh, this parameter defines the input channel to receive the measured specimen's deformation from the external LVDT.

NICON-AIO User Interface¶

The control buttons and indicators are located in different panels and each panel has one or more tabs. The functions and meanings of each button and indicator are explained in the following. The figure below shows a screenshot of the NICON front panel.

A. Command Source Panel¶

This panel shows information about the command source. The command source could be a numerical model, manually input commands, or a file containing displacement history. In the current hybrid simulation, the OpenSees numerical model communicates with NICON as the command source.

A.I. Network Tab¶

The network tab is shown below. During the hybrid simulation, this tab shows information about the OpenSees model and the communication status between the numerical model and NICON.

Indicators:

Port Number: This number is defined in the NICON configuration file. It should match the port number defined in the numerical model. In the OpenSees numerical model, the port number is specified in the ‘Structufile.txt’ file, discussed earlier.

CMD recvd: This indicator shows the command status, and not the command itself. This indicator will show either 3, or 10. When it is showing 3, it means NICON is receiving the command from OpenSees and, when showing 10, it means that NICON is commanding the controller or reporting back to OpenSees.

Current Step Number: This indicator shows the number of the current time-step during the test. It can be useful for monitoring the progress of the test.

received target Displacement: This indicator shows the target displacement that OpenSees sends to NICON. This displacement is the target displacement of the specimen by the end of an increment.

SocketNum: This number is used to set up a connection between NICON and the numerical OpenSees model. It is pre-defined in the substructural module that is used in OpenSees and does not need to be changed by the user.

Status lights:

Create data exchange format: The received data and the data that is sent out from NICON must have the same DOFs. Since NICON receives displacements and sends back both displacement and force, the size of the information components that are sent out should always be twice as the number of received information components. In the SDOF case, NICON receives one displacement and sends one displacement and one force feedback to OpenSees at every communication increment.

Connected: The ‘Connected’ light will go on when the connection is established.

Waiting CMD: This light is turned on when OpenSees is processing data. This is after NICON sends force and displacement feedback to OpenSees and before NICON receives the new displacement command from OpenSees.

Testing: This light will turn on during the time it takes for NICON to send the displacement and force measurements back to OpenSees, after receiving a displacement command.

Reporting: This light turns on when NICON sends all feedback into the communication library. It turns off very quickly.

Completed: This light turns on when the simulation is completed.

NC Status: This light turns on when a new command is received and NICON is ready for testing.

Ready to Read the Values: This light turns on when NICON is ready to receive the new displacement command, in the simulation.

Button:

Start Server: By clicking on this button, NICON will await setting up the connection with the numerical model. In the current version, NICON will be frozen after the button is clicked and will be back to normal when the connection is set up successfully.

Start Communication: This button will start the procedure of sending/receiving data. Note that merely starting the server, and setting up the connection will not enable sending/receiving of data, until this button is pressed. This button must be pressed when everything is ready in the test setup.

A.II. User Input Tab¶

This tab is used for cases when it is desired to apply manual commands to the actuator controller. In hybrid simulations using NICON, the offset functions are used before the test. A screenshot of the user input tab is shown below.

A.III. Time-History Tab¶

The time-history tab is used to apply a pre-defined command path to the specimen. It could represent a ground motion, a cyclic displacement, or a monotonic displacement command. The Time-History tab of the example NICON version is shown below.

B. Control Panel¶

Information specified in this panel includes simulation parameters. Most of the values are pre-set in the NICON configuration file and are merely displayed in this panel.

B.I. Control Tab¶

The control tab of the NICON version is shown below. This tab displays information on displacement commands and some of the NICON control parameters.

Indicators:

Previous Target Disp: This number shows the target specimen's displacement of the previous analysis step.

Current Target Disp: This number shows the target specimen's displacement of the current analysis step.

Previous Target Stroke: This number displays the target actuator stroke of the previous iteration.

Current Target Stroke: This number displays the target actuator stroke of the current iteration.

Iteration: This is the completed number of iterations for the current analysis step.

Current Specimen Disp: This is the actual specimen's displacement at the current iteration.

Current Command Disp: This is the displacement command at the current iteration.

Current stroke Disp: This is the measured actuator stroke at the current iteration.

Current Specimen Disp top: This is the actual displacement of one of the specimen's ends (e.g., Node j) at the current iteration (Optional).

Current Specimen Disp bot: This is the actual displacement of the other specimen's end (e.g., Node i) at the current iteration (Optional).

Ramp: This number shows the ramp time for each displacement increment.

Hold: This number shows the hold time after each ramp.

Analog I/O update rate (ms): This number specifies the sampling rate for both the actuator controller measurements and the commands sent from NICON to the actuator controller.

Analog I/O logging rate (ms): This number will specify the rate with which the communication between NICON and the controller will be recorded in the log file.

Status Lights:

Displacement Limit Status: This light indicates whether the displacement limit is met before sending the command to the actuator controller. The upper and lower bounds of the displacement limit can be adjusted in the NICON configuration file, or in the limits tab.

Force Limit Status: This light indicates whether the force limit is met. The upper and lower bounds of the displacement limit can be adjusted in the NICON configuration file, or the limits tab.

Buttons:

Rampmode: This button can be used to turn ramp mode on or off. The ramp mode is on by default.

Manual-Auto switch: This button is used to switch between the manual mode and the auto mode. When on the auto mode, NICON is controlled by the numerical model. When on the manual mode, each analysis step must be executed manually by clicking on the ‘Execute Target CMD’ button. During the hybrid simulation, NICON mode can be switched from the auto mode to the manual mode, or from the manual mode from the auto mode.

Execute Target CMD: This button is used to send displacement commands to the actuator controller manually.

Cancel: This button can be used to terminate the execution of the current displacement command, under the manual mode.

Control: When the control button is switched on, NICON will take control of the controller. If the control button is not on, NICON will not send any commands to the actuator. By activating the control button before starting the analysis, NICON will send displacement commands to the actuator controller that are equal to the measured displacements, received from the numerical model.

B.II. Limits Tab¶

The Limits tab for the provided NICON version is shown below. Force and displacement limits are shown and can be specified in this tab. The user can adjust the limits during the test as well. The limits specified here relate to the total actuator displacement stroke and force. In other words, the values before offset.

Also specified in this tab, is the displacement increment limit. This is to ensure that a large displacement is not applied suddenly to the specimen during the test. In addition, a sudden large displacement may be an indication of an error in the system. Therefore, if this limit is exceeded, the user can check the test setup. To facilitate this, NICON is programmed to automatically switch to the Manual mode, when this limit is exceeded.

B.III. Scale Factors¶

The figure below shows the screenshot of the Scale Factors Tab. The factors in this tab are set according to the controller’s specification. Scale factors and the I/O channel cannot be changed during the test. It is recommended that before every test, it is checked if the channels are connected correctly and proper scale factors are used. For the featured example, the output command is communicated using differential signaling, while the input force/displacement measurements are communicated using single-ended signaling.

B.IV. Sub-structure Info¶

The figure below shows a screenshot of the Sub-structure Info Tab where users can configure the interface nodes and the effective DOFs for communication with the numerical model. Depending on the options (Option 1 to 4) for "activate dofs", up to two nodes of the interface element with two or three effective DOFs per node can be used. With the user-defined coordinates of the interface nodes (starts with node i and ends with node j), NICON-AIO performs the necessary coordinate transformation to obtain the quantities (displacement and force) along the axial direction of the specimen automatically.

B.V. Error Compensation¶

The figure below shows a screenshot of the Error Compensation Tab where users can define the gain value, the maximum number of iterations, and the error tolerance for the implemented error compensation function.

B.VI. ACTIA¶

The figure below shows a screenshot of the ACTIA Tab. ACTIA is a Python script to automate the image acquisition during the hybrid simulation. NICON-AIO can send a triggering command to ACTIA through the TCP/IP network protocol to take photos for each simulation step.

C. Monitoring Panel¶

All received and output voltages as well as corresponding forces and displacements are displayed in this panel. The Monitoring Panel consists of three tabs, as described below.

C.I. Time History Tab¶

The Time-History tab is shown below. Displacement (both command and measured) and measured force history are shown in this tab. Actual/Tared switch changes the display of displacement/force, from absolute measurement to the measured value from offset, and does not influence the commands.

C.II. Force-Displacement Tab¶

The Force-Displacement tab is shown below. The graph displays the specimen force vs. specimen displacement during the test. The graph records tared value of force and displacement. Therefore, if the Reset F-D Graph button is not clicked on, jumps in both force and displacement may be observed. It must be noted that this is only a display panel and the results or the commands are not influenced.

C.III. Raw Voltage Tab¶

As shown below, the input and output voltages are displayed here. In the current example, if the actuator follows the command well, there is no significant difference between input and output voltage. The NI hardware can output a maximum voltage of 10 V, so that sets the maximum actual displacement.

Run Hybrid Simulation¶

To run a hybrid simulation of the example structure, the following steps should be used.

1. Connect the DAQ device to the actuator controller. Ensure that the input/output connected channels for displacement and force are consistent with the channel number defined in the NICON configuration file.

2. Power the NI DAQ device. The NI hardware is powered by connecting it to the computer through a USB cord.

3. Run NICON. This can be done by clicking the run button on the left up corner. At this stage, NICON only reads force and displacement measurements from the actuator controller. Ensure that the readings in NICON are reasonable.

4. Adjust the actuator stroke to be in a convenient position. This can be done by adjusting the actuator position in the User Input tab, in the Command Source Panel. This is mainly used for placing the specimen in the initial position for the test.

5. Click on the control button in the Control Panel in NICON. After the Control light is on, NICON starts to send out displacement command to the actuator controller equal to the received displacement measurements from the actuator controller. This is carried out to ensure that the specimen will not experience any sudden displacement command when the Control is turned on.

6. Reset the force and displacement origins, in the Command Source Panel, in the User input tab. This can be carried out by enabling the ‘Allow Offset’ switch. Afterwards, the ‘Reset Force Origin’ and the ‘Reset Displacement Origin’ buttons are activated and can be used. Reset the force origin and the displacement origin. The amount of offset is the current reading of force and displacement. This is carried out to ensure that the test data start from zero displacement and zero force states. Zero the force reading in the MTS station Manager and reset displacement and external command origins.

7. Switch the control source of the controller from internal to external by click the run button in MTS Station Manager. At this moment, NICON takes over the control.

8. Check whether the displacement of the stroke remains the same as before (i.e., close to zero)

9. Specify a displacement command (e.g., 1 mm) from the User Input tab in NICON and click Execute Target CMD button to impose the displacement command to the controller. Check whether the actuator moves the same amount of displacement as specified in NICON. If everything goes well, move the actuator back to the origin by specifying a zero displacement command from the User Input tab in NICON and clicking "Execute Target CMD". Check whether the actuator moves back as expected.

10. If the error compensation is required, click on the "EC ON/OFF" button in the Error Compensation tab to enable the error compensation scheme.

11. If the ACTIA is used, firstly run the ACTIA script and then click on the "ACTIA" button in the ACTIA Tab followed by the "Start ServerACT" button to establish the connection between ACTIA and NICON-AIO.

12. Click on the "Start Server" button in the Command Source panel. NICON will wait for the connection with the numerical integration module.

13. Run the OpenSees model

14. Click on the "Start Communication" button in the Command Source panel. OpenSees numerical model will start to send displacement commands to NICON. The test can start at this stage.

15. After ensuring that the test is running properly, switch the simulation mode to Auto. The simulation will continue. The simulation will be stopped and automatically switched to the manual mode, if a limit is exceeded during the simulation. In such a case, an error message will appear with information about the exceeded limit, error, and instructions on how to continue with the test.

16. When the test is finished, NICON will turn into the Manual mode. Switch the control source for the actuator controller, from external back to internal by clicking the stop button in MTS Station Manager, then turn off NICON by simply closing the NICON-AIO window.

17. After the simulation, a set of \.log* files will be generated in the folders containing NICON, and the OpenSees integration module. Ensure that the generated .log files are retrieved before re-running the test. This is carried out to avoid overwriting and mixing of the files during the next simulations. The log files are discussed in the following section.

Log Files Generated by NICON-AIO (1DOF)¶

Three types of log files are created by NICON in the "log files" folder.

1. Analog IO_XXXXXXXX.log. Note that "XXXXXXXX" shows the month, date, hour, and the minute (i.e., 11011919 means that the file was created in Nov 19 at 19:19). Five columns are recorded in this file

   • Column 1: Clock time (time stamp) when the data is recorded. Time increment for recording data is based on the Analog I/O logging rate (ms), specified in the Control tab, in the Control Panel.
   • Column2: This column shows the actuator stroke command. Note that this shows the actual actuator stroke (not accounting for the offset).
   • Column3: Output voltage to the controller, at the specified time in Column 1, which identifies the displacement command.
   • Column4: Input voltage from the controller, which identifies the measured displacement, at the specified time in Column 1. The actual stroke displacement can be calculated by multiplying this number with the scale factors.
   • Column5: This column shows the voltage input from the load cell, at the specified time.
   • Column6: Measured displacement of the specimen.
   • Column7: Measured force at the specified time.

2. Network_XXXXXXXX.log. The same description above applies to ‘xxxxxxxx’ for the Network .log file. In the Network Log file, data is recorded at every increment at which OpenSees sends target displacement to NICON and NICON sends measured displacements and forces to OpenSees. Five columns are recorded in this file:

   • Column1: Time of communication.
   • Column2: State of communication (Sent vs. Received)
   • Column3: Communication command mode. CMD 3, shows that a new displacement command is sent from the integration module. CMD 10-Recevied shows that the new command is received in NICON. CMD 10-Sent, shows that the feedback is sent back to the integration module. CMD 99 shows the final step of the simulation and identifies that the simulation has ended.
   • Column4: This column shows the command/measured displacements, for each communication state, in each step.
   • Column5: This column shows the measured force, for the corresponding communication state, in each step.

3. DispXXXXXXXX.log. The same description above applies to ‘xxxxxxxx’ for this log file. This file record the data used for error compensation. Five columns are recorded in this file:

   • Column1: Time of communication
   • Column2: Current target displacement command
   • Column3: Current target stroke
   • Column4: Current specimen’s displacement
   • Column5: Current actuator’s stroke