ETABS and SAP2000

Introduction

This guide provides detailed instructions for setting up the VIKTOR worker with the CSI software suite, focusing specifically on ETABS and SAP2000. The steps outlined are also applicable to other CSI tools. It is designed to offer the necessary context and file templates to facilitate the integration process.

The worker

A worker is a program that connects the VIKTOR platform to third-party software running outside the platform. You can install the worker on your local machine or a remote server, but the CSI software must be installed where the worker is located. Your VIKTOR app will handle the communication between the web app and the worker as shown in the following diagram.

Here is what happens during the integration:

1. The user enters input parameters in the VIKTOR UI.
2. The app.py in the VIKTOR app sends these parameters to the worker.
3. The worker (running on your local machine or a virtual machine) creates the model using the input parameters in ETABS/SAP2000.
4. The worker sends back the result of the calculation to your VIKTOR app.
5. VIKTOR UI displays the result of the calculation.

Install a generic worker

Follow these steps to install the worker:

Development

1. Navigate to the "My Integrations" tab in your personal settings

2. Click "Add integration"

3. Follow the steps provided in the modal

   

   3.1. Select Other

   3.2. Download the worker .msi (Microsoft Installer) and run it on the machine of choice

   3.3. Copy the generated connection key and paste it when the installer asks for it

Published App

caution

You need to be an environment administrator in order to install a worker for a published app.

1. Navigate to the "Integrations" tab in the Administrator panel

2. Click "Add integration"

3. Follow the steps provided in the modal

   

   3.1. Select Other

   3.2. Select the workspace(s) the integration should be available to

   3.3. Download the worker .msi (Microsoft Installer) and run it on the machine of choice

   3.4. Copy the generated connection key and paste it when the installer asks for it

Connection Key

The generated connection key should be copied immediately as VIKTOR will not preserve this data for security reasons.

Configure the worker

The worker will control ETABS and SAP2000 through a Python environment where pywin32 and comtypes need to be installed. This environment can be on your local Windows machine or a remote server where the CSI software is installed with a valid license. For this integration, we will set up the worker in a separate folder from the VIKTOR app, simulating a remote setup.

Step 1: Create the worker directory

1. Navigate to your C:\ directory using the Windows Explorer.
2. Create a new folder named EtabsServer to store the worker files.

Step 2: Set up Python and install dependencies

1. Ensure that the correct Python environment is being used to execute the code. To locate the Python executable in your development environment, run the following command in your terminal:

where python

The result should provide the path to the Python executable. It will likely look something like:

C:\Program Files\PythonXX\

Or:

C:\Users\<YourUsername>\AppData\Local\Programs\Python\PythonXX\

Make sure to save this path, as your worker will use it to run Python code related to the CSI API.

2. Now, install the necessary libraries (pywin32 and comtypes) using pip in the identified Python environment:

pip install pywin32 comtypes

This Python environment will be used to execute all Python code that involves working with the CSI API.

Let’s proceed with the YAML configuration file.

Step 3: YAML file configuration

1. Navigate to the worker installation directory. By default, this is located at:
   'C:\Program Files\VIKTOR\'

2. Open the config.yaml file. You will see something like this:

executables:  
 some_executable:  
   path: 'C:\path\to\executable.exe'  
   arguments:  
	 - '-arg1'  
	 - '-arg2'  
	 - '-arg3'  
   workingDirectoryPath: 'C:\path\to\script'  
maxParallelProcesses: 1

3. Now, modify it with your actual Python path (the one you kept from step 2) and fill out the rest of the YAML configuration.

executables:  
  run_etabs:  
    path: 'C:\Users\<YourUsername>\AppData\Local\Programs\Python\PythonXX\'
    arguments:
      - 'run_etabs_model.py'
    workingDirectoryPath: 'C:\EtabsServer' 
maxParallelProcesses: 1

Note that in the arguments value, we add a Python file called run_etabs_model.py. This file will be located in your VIKTOR app folder, and we will push it to the workingDirectoryPath to be executed.

4. Save the config.yaml file.

5. Finally, restart the worker from the task scheduler.

note

For SAP2000, just replace “etabs” with “sap” and “EtabsServer” with “SapServer”.

The following directory structure can be used as a template when working with the ETABS and SAP2000 API:

my-etabs-app/
├── run_etabs_model.py
├── app.py
├── inputs.json
├── output.json

Here is the role of each file:

• The app.py contains your VIKTOR app that includes the logic of your Controller and Parametrization classes. This file generates an inputs.json file based on the inputs you define in your app.

• The worker is responsible for copying and sending the run_etabs_model.py and inputs.json files to our EtabsServer folder. Then, the worker executes the run_etabs_model.py using the Python environment defined in the config.yaml.

• The output.json is generated after execution in the EtabsServer folder. Then the worker sends back this file and its content to your VIKTOR app.

• Your VIKTOR app receives the output.json and displays it in the web app.

You can use the following app.py template to set up the communication with your worker:

# app.py
import viktor as vkt
from pathlib import Path

class Parametrization(vkt.Parametrization):
    ...

class Controller(vkt.Controller):
    ...
	# A function inside the Controller creates the `inputs.json`.
    
    def run_etabs(self, params, **kwargs):
        inputs_path = Path(__file__).parent / "inputs.json"
        script_path = Path(__file__).parent / "run_etabs_model.py"
        files = [
            ("inputs.json", vkt.File.from_path(inputs_path)), 
            ("run_etabs_model.py", vkt.File.from_path(script_path))
        ]
        # Note that executable_key matches the config.yaml of the worker (run_etabs)
        generic_analysis = vkt.external.GenericAnalysis(
            files=files, 
            executable_key="run_etabs", 
            output_filenames=["output.json"]
        )
        generic_analysis.execute(timeout=300)
        output_file = generic_analysis.get_output_file("output.json", as_file=True)

The following template can be used to define the content of your run_etabs_model.py to communicate with the worker and your VIKTOR app:

# run_etabs_model.py
import json
from pathlib import Path

def create_etabs_model():
    
    ''' 
    1. Your code reads the inputs.json file and 
    uses the content for structural analysis in ETABS.
    '''
    input_json = Path.cwd() / "inputs.json"
    with open(input_json) as jsonfile:
        data = json.load(jsonfile)
    
    ''' 
    2. Add your logic here for the analysis 
    using the ETABS API.
    '''

    '''
    3. Store the results of your analysis
    in the output.json file to be sent to 
    your VIKTOR app.
    '''
    output = Path.cwd() / "output.json"
    with open(output, "w") as jsonfile:
        json.dump(outputs, jsonfile)

create_etabs_model()

info

You can check the following tutorial to see the worker in action!

Conclusion

By following this guide, you’ve learned how to set up your worker and now have the templates you need to integrate SAP2000 and ETABS with your app. You’re ready to automate all your designs and analysis.