Skip to main content

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.

worker

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 an ETABS worker​

Follow these steps to install the worker:

  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 ETABS

    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. In the browser, you can now click Finish. Continue the installation in the installer wizard.

    Connection Key

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

  4. In the installer wizard, select the Python executable of your choice, this can be your system Python, or the python.exe in a dedicated virtual environment

    tip

    Your default Python environment can usually be found in

    C:\Users\Username\AppData\Local\Programs\Python\Python31X\python.exe

    If you cannot find it, try running the following command in your terminal

    where python

  5. Make sure to launch the worker once the installation is finished. If you closed the integration, you can restart it through the desktop shortcut.

note

For SAP2000, follow the same steps, but select SAP2000 instead.

Install Python dependencies​

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.

  1. Install the necessary libraries (pywin32 and comtypes) using pip in the python environment selected during installation:
pip install pywin32 comtypes

Set up the app​

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

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

This is the role of each file:

  • The app.py contains the logic of your VIKTOR app. It will use the inputs.json file as input for the worker and reads the output.json generated by the worker.

  • The worker executes the run_etabs_model.py using the Python environment defined during worker installation (also defined in the config.yaml). This file will generate output.json which is send back to the VIKTOR 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):
        script = vkt.File.from_path(Path(__file__).parent / "run_etabs_model.py")
        files = [("inputs.json", vkt.File.from_path(Path(__file__).parent / "inputs.json"))]
        analysis = vkt.etabs.ETABSAnalysis(
            script=script, files=files, output_filenames=["output.json"]
        )
        analysis.execute(timeout=300)
        output_file = analysis.get_output_file("output.json")

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.

Testing​

ETABSAnalysis.execute needs to be mocked within the context of (automated) testing.

The viktor.testing module provides the mock_ETABSAnalysis decorator that facilitate mocking of workers:

import unittest

import viktor as vkt

from viktor.testing import mock_ETABSAnalysis

from app.my_entity_type.controller import MyEntityTypeController


class TestMyEntityTypeController(unittest.TestCase):
    @mock_ETABSAnalysis(get_output_file={
        'result.xml': vkt.File.from_path('test_file.xml'),  # <name>: <File>
        'result.json': vkt.File.from_path('test_file.json'),
        ...
    })
    def test_analysis(self):
        MyEntityTypeController().analysis()

For the decorator's input parameters the following holds:

  • If a Sequence type is provided, the next entry is returned for each corresponding method call. When a call is performed on a depleted iterable, an Exception is raised.
  • If a single object is provided, the object is returned each time the corresponding method is called (endlessly).
  • If None is provided (default), a default File/BytesIO object (with empty content) is returned each time the corresponding method is called (endlessly).