pytabs.model

  1# pyTABS - ETABS .NET API python wrapper
  2# EtabsModel object and cFile interface
  3__all__ = ['EtabsModel']
  4
  5# general library imports
  6from pathlib import Path
  7
  8# import ETABS namespace and pyTABS error handler
  9from pytabs.etabs_config import *
 10from pytabs.error_handle import handle, EtabsError
 11
 12# import pyTABS custom enumerations
 13from pytabs.enumerations import eFrameDesignProcedure
 14
 15
 16# import typing
 17from typing import Union, TypedDict
 18
 19# import of ETABS API interface wrappers
 20from pytabs.analyse import Analyse
 21from pytabs.analysis_results import AnalysisResults
 22from pytabs.analysis_results_setup import AnalysisResultsSetup
 23from pytabs.area_elm import AreaElm
 24from pytabs.area_obj import AreaObj
 25from pytabs.combo import Combo
 26from pytabs.constraint import Constraint
 27from pytabs.database_tables import DatabaseTables
 28from pytabs.diaphragm import Diaphragm
 29from pytabs.frame_obj import FrameObj
 30from pytabs.grid_sys import GridSys
 31from pytabs.group import Group
 32from pytabs.line_elm import LineElm
 33from pytabs.link_obj import LinkObj
 34from pytabs.load_cases import LoadCases
 35from pytabs.load_patterns import LoadPatterns
 36from pytabs.pier_label import PierLabel
 37from pytabs.point_elm import PointElm
 38from pytabs.point_obj import PointObj
 39from pytabs.property import Property
 40from pytabs.select import Select
 41from pytabs.spandrel_label import SpandrelLabel
 42from pytabs.story import Story
 43from pytabs.tendon_obj import TendonObj
 44from pytabs.tower import Tower
 45from pytabs.view import View
 46
 47
 48class UnitsComponents(TypedDict):
 49    """TypedDict class for Units components return"""
 50    force_units : etabs.eForce
 51    length_units : etabs.eLength
 52    temperature_units : etabs.eTemperature
 53
 54
 55class EtabsModel():
 56    """pytabs ETABS Model Object `EtabsObject` 🏢. 
 57    
 58    All interfaces and enumerations to the Etabs model objects are accessed as properties - refer below.
 59    
 60    """
 61    def __init__(self,
 62                 attach_to_instance : bool = True,
 63                 specific_etabs : bool = False,
 64                 specific_etabs_path : Union[str, Path] = '',
 65                 model_path : Union[str, Path] = '',
 66                 remote_computer : str = '') -> None:
 67        
 68        # relate ETABS interfaces
 69        self.analyse : Analyse
 70        """EtabsModel `Analyse` interface."""
 71        self.analysis_results_setup : AnalysisResultsSetup
 72        """EtabsModel `AnalysisResultsSetup` interface."""
 73        self.analysis_results : AnalysisResults
 74        """EtabsModel `AnalysisResults` interface."""
 75        self.area_elm : AreaElm
 76        """EtabsModel `AreaElm` interface."""
 77        self.area_obj : AreaObj
 78        """EtabsModel `AreaObj` interface."""
 79        # individual case interfaces to be accessed via LoadCase interface
 80        self.combo : Combo
 81        """EtabsModel `Combo` interface."""
 82        self.constraint : Constraint
 83        """EtabsModel `Constraint` interface."""
 84        self.database_tables : DatabaseTables
 85        """EtabsModel `DatabaseTables` interface."""
 86        self.diaphragm : Diaphragm
 87        """EtabsModel `Diaphragm` interface."""
 88        self.frame_obj : FrameObj
 89        """EtabsModel `FrameObj` interface."""
 90        self.grid_sys : GridSys
 91        """EtabsModel `GridSys` interface."""
 92        self.group : Group
 93        """EtabsModel `Group` interface."""
 94        self.line_elm : LineElm
 95        """EtabsModel `LineElm` interface."""
 96        self.link_obj : LinkObj
 97        """EtabsModel `LinkObj` interface."""
 98        self.load_cases : LoadCases
 99        """EtabsModel `LoadCases` interface."""
100        self.load_patterns : LoadPatterns
101        """EtabsModel `LoadPatterns` interface."""
102        self.point_elm : PointElm
103        """EtabsModel `PointElm` interface."""
104        self.point_obj : PointObj
105        """EtabsModel `PointObj` interface."""
106        self.pier_label : PierLabel
107        """EtabsModel `PierLabel` interface."""
108        # individual prop interfaces to be accessed via Property interface
109        self.property : Property
110        """EtabsModel `Property` interface."""
111        self.select : Select
112        """EtabsModel `Select` interface."""
113        self.spandrel_label : SpandrelLabel
114        """EtabsModel `SpandrelLabel` interface."""
115        self.story : Story
116        """EtabsModel `Story` interface."""
117        self.tendon_obj : TendonObj
118        """EtabsModel `TendonObj` interface."""
119        self.tower : Tower
120        """EtabsModel `Tower` interface."""
121        self.view : View
122        """EtabsModel `View` interface."""
123        
124        # relate ETABS cross interface enumerations
125        self.eAreaDesignOrientation = etabs.eAreaDesignOrientation
126        """EtabsModel `AreaDesignOrientation` enumeration."""
127        self.eForce = etabs.eForce
128        """EtabsModel `Force` enumeration."""
129        self.eFrameDesignOrientation = etabs.eFrameDesignOrientation
130        """EtabsModel `FrameDesignOrientation` enumeration."""
131        self.eItemType = etabs.eItemType
132        """EtabsModel `ItemType` enumeration"""
133        self.eItemTypeElm = etabs.eItemTypeElm
134        """EtabsModel `ItemTypeElm` enumeration"""
135        self.eLength = etabs.eLength
136        """EtabsModel `Length` enumeration."""
137        self.eLoadPatternType = etabs.eLoadPatternType
138        """EtabsModel `LoadPatternType` enumeration"""
139        self.eObjType = etabs.eObjType
140        """EtabsModel `ObjType` enumeration"""
141        self.eTemperature = etabs.eTemperature
142        """EtabsModel `Temperature` enumeration."""
143        self.eUnits = etabs.eUnits
144        """EtabsModel `Units` enumeration."""
145        
146        # relate pyTABS custom enumerations
147        self.eFrameDesignProcedure = eFrameDesignProcedure
148        
149        # EtabsModel initial properties
150        self.pytabs_config = pytabs_config
151        """pyTABS config file (pytabs_config.ini)"""
152        self.active : bool = False
153        """`True` if EtabsModel is active, otherwise `False`."""
154        self.model_open : bool = False
155        """`True` if model open, otherwise `False`."""
156        self.model_path : Union[str, Path] = ''
157        """Etabs model filepath."""
158        
159        # create ETABS API helper interface and try to initialise EtabsObject
160        helper = etabs.cHelper(etabs.Helper())
161        if attach_to_instance:
162            # attach to a running instance of ETABS
163            try:
164                # get the active ETABS object        
165                if remote_computer:
166                    self.etabs_object = etabs.cOAPI(helper.GetObjectHost(remote_computer, "CSI.ETABS.API.ETABSObject"))
167                else:
168                    self.etabs_object = etabs.cOAPI(helper.GetObject("CSI.ETABS.API.ETABSObject"))
169                self.active = True
170            except:
171                raise EtabsError(-1, "No running instance ETABS found or failed to attach.")
172        else:
173            if specific_etabs:
174                try:
175                    # create an instance of the ETABS object from the specified path
176                    if remote_computer:
177                        self.etabs_object = etabs.cOAPI(helper.CreateObjectHost(remote_computer, str(specific_etabs_path)))
178                    else:
179                        self.etabs_object = etabs.cOAPI(helper.CreateObject(str(specific_etabs_path)))
180                    self.active = True
181                except :
182                    raise EtabsError(-1, f"Cannot start a new instance of the ETABS from {str(specific_etabs_path)}")
183            else:
184                try: 
185                    # create an instance of the ETABS object from the latest installed ETABS
186                    if remote_computer:
187                        self.etabs_object = etabs.cOAPI(helper.CreateObjectProgIDHost(remote_computer, "CSI.ETABS.API.ETABSObject"))
188                    else:
189                        self.etabs_object = etabs.cOAPI(helper.CreateObjectProgID("CSI.ETABS.API.ETABSObject"))
190                    self.active = True
191                except:
192                    raise EtabsError(-1, "Cannot start a new instance of ETABS.")
193            # start etabs application
194            self.etabs_object.ApplicationStart()
195        
196        # if EtabsObject active 
197        if self.active:
198            # create SapModel interface
199            self.sap_model = etabs.cSapModel(self.etabs_object.SapModel)
200            """EtabsModel `SapModel` interface."""
201            # create File interface
202            self.file = etabs.cFile(self.sap_model.File)
203            
204            # relate external pyTABS interfaces
205            self.analyse = Analyse(self.sap_model)
206            self.analysis_results_setup = AnalysisResultsSetup(self.sap_model)
207            self.analysis_results = AnalysisResults(self.sap_model)
208            self.area_elm = AreaElm(self.sap_model)
209            self.area_obj = AreaObj(self.sap_model)
210            # individual case interfaces to be accessed via LoadCase interface
211            self.combo = Combo(self.sap_model)
212            self.constraint = Constraint(self.sap_model)
213            self.database_tables = DatabaseTables(self.sap_model)
214            self.diaphragm = Diaphragm(self.sap_model)
215            self.frame_obj = FrameObj(self.sap_model)
216            self.grid_sys = GridSys(self.sap_model)
217            self.group = Group(self.sap_model)
218            self.line_elm = LineElm(self.sap_model)
219            self.link_obj = LinkObj(self.sap_model)
220            self.load_cases = LoadCases(self.sap_model)
221            self.load_patterns = LoadPatterns(self.sap_model)
222            self.pier_label = PierLabel(self.sap_model)
223            # individual property interfaces to be accessed via Property interface
224            self.property = Property(self.sap_model)
225            self.select = Select(self.sap_model)
226            self.spandrel_label = SpandrelLabel(self.sap_model)
227            self.story = Story(self.sap_model)
228            self.tendon_obj = TendonObj(self.sap_model)
229            self.tower = Tower(self.sap_model)
230            self.view = View(self.sap_model)
231
232            # if not attached to instance and model path supplied open model
233            if (not attach_to_instance) and model_path:
234                self.open_model(model_path)
235
236
237    def exit_application(self):
238        '''Terminates ETABS application severing API connection'''
239        self.etabs_object.ApplicationExit(False)
240        self.model_open = False
241        self.model_path = ''
242        self.sap_model = None
243        self.active = False
244
245
246    def open_model(self, model_path: Union[str, Path]) -> None:
247        """Opens ETABS model file.
248
249        :param model_path: file path to ETABS model file
250        :type model_path: Union[str, Path]
251        """
252        handle(self.file.OpenFile(str(model_path)))
253        self.model_path = model_path
254        self.model_open = True
255
256
257    def new_model(self, new_model_path: Union[str, Path]) -> None:
258        """Creates new blank ETABS model and saves.
259
260        :param new_model_path: file path to save new blank ETABS model file
261        :type new_model_path: Union[str, Path]
262        """
263        handle(self.file.NewBlank())
264        handle(self.file.Save(str(new_model_path)))
265        self.model_path = new_model_path
266        self.model_open = True
267        
268        
269    def get_database_units(self) -> etabs.eUnits:
270        """Returns a value from the eUnits enumeration indicating the database units for the model.
271        All data is internally stored in the model in these units and converted to the present units as needed.
272
273        :raises EtabsError: Database units could not be returned
274        :return: Units enumeration
275        :rtype: eUnits
276        """
277        self.sap_model.GetDatabaseUnits()
278        if ret == 0:
279            raise EtabsError(0, "Database units could not be returned.")
280        else:
281            return ret
282
283
284    def get_database_units_components(self) -> UnitsComponents:
285        """Retrieves the database units for the model.
286        All data is internally stored in the model in these units and converted to the present units as needed.
287
288        :return: units for force, length and temperature units
289        :rtype: UnitsComponents
290        """
291        force_units = etabs.eForce.NotApplicable
292        length_units = etabs.eLength.NotApplicable
293        temperature_units = etabs.eTemperature.NotApplicable
294        [ret, force_units, length_units, temperature_units] =  self.sap_model.GetDatabaseUnits_2(force_units, length_units, temperature_units)
295        handle(ret)
296        return {'force_units': force_units,
297                'length_units': length_units,
298                'temperature_units': temperature_units}
299
300
301    def get_model_is_locked(self) -> bool:
302        """Retrieves locked status of the model.
303
304        :return: True if model is looked, otherwise False
305        :rtype: bool
306        """
307        return self.sap_model.GetModelIsLocked()
308    
309    
310    def get_present_coord_system(self) -> str:
311        """Retrieves model present coordinate system.
312
313        :return: name of coordinate system
314        :rtype: str
315        """
316        return self.sap_model.GetPresentCoordSystem()
317
318
319    def get_present_units(self) -> etabs.eUnits:
320        """Returns a value from the eUnits enumeration indicating the units presently specified for the model.
321
322        :raises EtabsError: Present units could not be returned
323        :return: Units enumeration
324        :rtype: eUnits
325        """
326        ret = self.sap_model.GetPresentUnits()
327        if ret == 0:
328            raise EtabsError(0, "Present units could not be returned.")
329        else:
330            return ret
331
332
333    def get_present_units_components(self) -> UnitsComponents:
334        """Retrieves the units presently specified for the model.
335
336        :return: units components for force, length and temperature units
337        :rtype: UnitsComponents
338        """
339        force_units = etabs.eForce.NotApplicable
340        length_units = etabs.eLength.NotApplicable
341        temperature_units = etabs.eTemperature.NotApplicable
342        [ret, force_units, length_units, temperature_units] =  self.sap_model.GetPresentUnits_2(force_units, length_units, temperature_units)
343        handle(ret)
344        return {'force_units': force_units,
345                'length_units': length_units,
346                'temperature_units': temperature_units}
347
348
349    def set_model_is_locked(self, lock_it : bool = True):
350        """Locks or unlocks the model.
351
352        :param lock_it: True to lock mode, False to unlock, defaults to True
353        :type lock_it: bool, optional
354        """
355        handle(self.sap_model.SetModelIsLocked(lock_it))
356    
357    
358    def set_present_units(self, units : etabs.eUnits):
359        """Sets the display (present) units.
360
361        :param units: Units enumeration to set.
362        :type units: eUnits
363        """
364        handle(self.sap_model.SetPresentUnits(units))
365
366
367    def set_present_units_components(self, force_units : etabs.eForce, length_units : etabs.eLength, temperature_units : etabs.eTemperature):
368        """Specifies the units for the model.
369
370        :param force_units: Force enumeration to set
371        :type force_units: eForce
372        :param length_units: Length enumeration to set
373        :type length_units: eLength
374        :param temperature_units: Temperature enumeration to set
375        :type temperature_units: eTemperature
376        """
377        handle(self.sap_model.SetPresentUnits_2(force_units, length_units, temperature_units))
class EtabsModel:
 56class EtabsModel():
 57    """pytabs ETABS Model Object `EtabsObject` 🏢. 
 58    
 59    All interfaces and enumerations to the Etabs model objects are accessed as properties - refer below.
 60    
 61    """
 62    def __init__(self,
 63                 attach_to_instance : bool = True,
 64                 specific_etabs : bool = False,
 65                 specific_etabs_path : Union[str, Path] = '',
 66                 model_path : Union[str, Path] = '',
 67                 remote_computer : str = '') -> None:
 68        
 69        # relate ETABS interfaces
 70        self.analyse : Analyse
 71        """EtabsModel `Analyse` interface."""
 72        self.analysis_results_setup : AnalysisResultsSetup
 73        """EtabsModel `AnalysisResultsSetup` interface."""
 74        self.analysis_results : AnalysisResults
 75        """EtabsModel `AnalysisResults` interface."""
 76        self.area_elm : AreaElm
 77        """EtabsModel `AreaElm` interface."""
 78        self.area_obj : AreaObj
 79        """EtabsModel `AreaObj` interface."""
 80        # individual case interfaces to be accessed via LoadCase interface
 81        self.combo : Combo
 82        """EtabsModel `Combo` interface."""
 83        self.constraint : Constraint
 84        """EtabsModel `Constraint` interface."""
 85        self.database_tables : DatabaseTables
 86        """EtabsModel `DatabaseTables` interface."""
 87        self.diaphragm : Diaphragm
 88        """EtabsModel `Diaphragm` interface."""
 89        self.frame_obj : FrameObj
 90        """EtabsModel `FrameObj` interface."""
 91        self.grid_sys : GridSys
 92        """EtabsModel `GridSys` interface."""
 93        self.group : Group
 94        """EtabsModel `Group` interface."""
 95        self.line_elm : LineElm
 96        """EtabsModel `LineElm` interface."""
 97        self.link_obj : LinkObj
 98        """EtabsModel `LinkObj` interface."""
 99        self.load_cases : LoadCases
100        """EtabsModel `LoadCases` interface."""
101        self.load_patterns : LoadPatterns
102        """EtabsModel `LoadPatterns` interface."""
103        self.point_elm : PointElm
104        """EtabsModel `PointElm` interface."""
105        self.point_obj : PointObj
106        """EtabsModel `PointObj` interface."""
107        self.pier_label : PierLabel
108        """EtabsModel `PierLabel` interface."""
109        # individual prop interfaces to be accessed via Property interface
110        self.property : Property
111        """EtabsModel `Property` interface."""
112        self.select : Select
113        """EtabsModel `Select` interface."""
114        self.spandrel_label : SpandrelLabel
115        """EtabsModel `SpandrelLabel` interface."""
116        self.story : Story
117        """EtabsModel `Story` interface."""
118        self.tendon_obj : TendonObj
119        """EtabsModel `TendonObj` interface."""
120        self.tower : Tower
121        """EtabsModel `Tower` interface."""
122        self.view : View
123        """EtabsModel `View` interface."""
124        
125        # relate ETABS cross interface enumerations
126        self.eAreaDesignOrientation = etabs.eAreaDesignOrientation
127        """EtabsModel `AreaDesignOrientation` enumeration."""
128        self.eForce = etabs.eForce
129        """EtabsModel `Force` enumeration."""
130        self.eFrameDesignOrientation = etabs.eFrameDesignOrientation
131        """EtabsModel `FrameDesignOrientation` enumeration."""
132        self.eItemType = etabs.eItemType
133        """EtabsModel `ItemType` enumeration"""
134        self.eItemTypeElm = etabs.eItemTypeElm
135        """EtabsModel `ItemTypeElm` enumeration"""
136        self.eLength = etabs.eLength
137        """EtabsModel `Length` enumeration."""
138        self.eLoadPatternType = etabs.eLoadPatternType
139        """EtabsModel `LoadPatternType` enumeration"""
140        self.eObjType = etabs.eObjType
141        """EtabsModel `ObjType` enumeration"""
142        self.eTemperature = etabs.eTemperature
143        """EtabsModel `Temperature` enumeration."""
144        self.eUnits = etabs.eUnits
145        """EtabsModel `Units` enumeration."""
146        
147        # relate pyTABS custom enumerations
148        self.eFrameDesignProcedure = eFrameDesignProcedure
149        
150        # EtabsModel initial properties
151        self.pytabs_config = pytabs_config
152        """pyTABS config file (pytabs_config.ini)"""
153        self.active : bool = False
154        """`True` if EtabsModel is active, otherwise `False`."""
155        self.model_open : bool = False
156        """`True` if model open, otherwise `False`."""
157        self.model_path : Union[str, Path] = ''
158        """Etabs model filepath."""
159        
160        # create ETABS API helper interface and try to initialise EtabsObject
161        helper = etabs.cHelper(etabs.Helper())
162        if attach_to_instance:
163            # attach to a running instance of ETABS
164            try:
165                # get the active ETABS object        
166                if remote_computer:
167                    self.etabs_object = etabs.cOAPI(helper.GetObjectHost(remote_computer, "CSI.ETABS.API.ETABSObject"))
168                else:
169                    self.etabs_object = etabs.cOAPI(helper.GetObject("CSI.ETABS.API.ETABSObject"))
170                self.active = True
171            except:
172                raise EtabsError(-1, "No running instance ETABS found or failed to attach.")
173        else:
174            if specific_etabs:
175                try:
176                    # create an instance of the ETABS object from the specified path
177                    if remote_computer:
178                        self.etabs_object = etabs.cOAPI(helper.CreateObjectHost(remote_computer, str(specific_etabs_path)))
179                    else:
180                        self.etabs_object = etabs.cOAPI(helper.CreateObject(str(specific_etabs_path)))
181                    self.active = True
182                except :
183                    raise EtabsError(-1, f"Cannot start a new instance of the ETABS from {str(specific_etabs_path)}")
184            else:
185                try: 
186                    # create an instance of the ETABS object from the latest installed ETABS
187                    if remote_computer:
188                        self.etabs_object = etabs.cOAPI(helper.CreateObjectProgIDHost(remote_computer, "CSI.ETABS.API.ETABSObject"))
189                    else:
190                        self.etabs_object = etabs.cOAPI(helper.CreateObjectProgID("CSI.ETABS.API.ETABSObject"))
191                    self.active = True
192                except:
193                    raise EtabsError(-1, "Cannot start a new instance of ETABS.")
194            # start etabs application
195            self.etabs_object.ApplicationStart()
196        
197        # if EtabsObject active 
198        if self.active:
199            # create SapModel interface
200            self.sap_model = etabs.cSapModel(self.etabs_object.SapModel)
201            """EtabsModel `SapModel` interface."""
202            # create File interface
203            self.file = etabs.cFile(self.sap_model.File)
204            
205            # relate external pyTABS interfaces
206            self.analyse = Analyse(self.sap_model)
207            self.analysis_results_setup = AnalysisResultsSetup(self.sap_model)
208            self.analysis_results = AnalysisResults(self.sap_model)
209            self.area_elm = AreaElm(self.sap_model)
210            self.area_obj = AreaObj(self.sap_model)
211            # individual case interfaces to be accessed via LoadCase interface
212            self.combo = Combo(self.sap_model)
213            self.constraint = Constraint(self.sap_model)
214            self.database_tables = DatabaseTables(self.sap_model)
215            self.diaphragm = Diaphragm(self.sap_model)
216            self.frame_obj = FrameObj(self.sap_model)
217            self.grid_sys = GridSys(self.sap_model)
218            self.group = Group(self.sap_model)
219            self.line_elm = LineElm(self.sap_model)
220            self.link_obj = LinkObj(self.sap_model)
221            self.load_cases = LoadCases(self.sap_model)
222            self.load_patterns = LoadPatterns(self.sap_model)
223            self.pier_label = PierLabel(self.sap_model)
224            # individual property interfaces to be accessed via Property interface
225            self.property = Property(self.sap_model)
226            self.select = Select(self.sap_model)
227            self.spandrel_label = SpandrelLabel(self.sap_model)
228            self.story = Story(self.sap_model)
229            self.tendon_obj = TendonObj(self.sap_model)
230            self.tower = Tower(self.sap_model)
231            self.view = View(self.sap_model)
232
233            # if not attached to instance and model path supplied open model
234            if (not attach_to_instance) and model_path:
235                self.open_model(model_path)
236
237
238    def exit_application(self):
239        '''Terminates ETABS application severing API connection'''
240        self.etabs_object.ApplicationExit(False)
241        self.model_open = False
242        self.model_path = ''
243        self.sap_model = None
244        self.active = False
245
246
247    def open_model(self, model_path: Union[str, Path]) -> None:
248        """Opens ETABS model file.
249
250        :param model_path: file path to ETABS model file
251        :type model_path: Union[str, Path]
252        """
253        handle(self.file.OpenFile(str(model_path)))
254        self.model_path = model_path
255        self.model_open = True
256
257
258    def new_model(self, new_model_path: Union[str, Path]) -> None:
259        """Creates new blank ETABS model and saves.
260
261        :param new_model_path: file path to save new blank ETABS model file
262        :type new_model_path: Union[str, Path]
263        """
264        handle(self.file.NewBlank())
265        handle(self.file.Save(str(new_model_path)))
266        self.model_path = new_model_path
267        self.model_open = True
268        
269        
270    def get_database_units(self) -> etabs.eUnits:
271        """Returns a value from the eUnits enumeration indicating the database units for the model.
272        All data is internally stored in the model in these units and converted to the present units as needed.
273
274        :raises EtabsError: Database units could not be returned
275        :return: Units enumeration
276        :rtype: eUnits
277        """
278        self.sap_model.GetDatabaseUnits()
279        if ret == 0:
280            raise EtabsError(0, "Database units could not be returned.")
281        else:
282            return ret
283
284
285    def get_database_units_components(self) -> UnitsComponents:
286        """Retrieves the database units for the model.
287        All data is internally stored in the model in these units and converted to the present units as needed.
288
289        :return: units for force, length and temperature units
290        :rtype: UnitsComponents
291        """
292        force_units = etabs.eForce.NotApplicable
293        length_units = etabs.eLength.NotApplicable
294        temperature_units = etabs.eTemperature.NotApplicable
295        [ret, force_units, length_units, temperature_units] =  self.sap_model.GetDatabaseUnits_2(force_units, length_units, temperature_units)
296        handle(ret)
297        return {'force_units': force_units,
298                'length_units': length_units,
299                'temperature_units': temperature_units}
300
301
302    def get_model_is_locked(self) -> bool:
303        """Retrieves locked status of the model.
304
305        :return: True if model is looked, otherwise False
306        :rtype: bool
307        """
308        return self.sap_model.GetModelIsLocked()
309    
310    
311    def get_present_coord_system(self) -> str:
312        """Retrieves model present coordinate system.
313
314        :return: name of coordinate system
315        :rtype: str
316        """
317        return self.sap_model.GetPresentCoordSystem()
318
319
320    def get_present_units(self) -> etabs.eUnits:
321        """Returns a value from the eUnits enumeration indicating the units presently specified for the model.
322
323        :raises EtabsError: Present units could not be returned
324        :return: Units enumeration
325        :rtype: eUnits
326        """
327        ret = self.sap_model.GetPresentUnits()
328        if ret == 0:
329            raise EtabsError(0, "Present units could not be returned.")
330        else:
331            return ret
332
333
334    def get_present_units_components(self) -> UnitsComponents:
335        """Retrieves the units presently specified for the model.
336
337        :return: units components for force, length and temperature units
338        :rtype: UnitsComponents
339        """
340        force_units = etabs.eForce.NotApplicable
341        length_units = etabs.eLength.NotApplicable
342        temperature_units = etabs.eTemperature.NotApplicable
343        [ret, force_units, length_units, temperature_units] =  self.sap_model.GetPresentUnits_2(force_units, length_units, temperature_units)
344        handle(ret)
345        return {'force_units': force_units,
346                'length_units': length_units,
347                'temperature_units': temperature_units}
348
349
350    def set_model_is_locked(self, lock_it : bool = True):
351        """Locks or unlocks the model.
352
353        :param lock_it: True to lock mode, False to unlock, defaults to True
354        :type lock_it: bool, optional
355        """
356        handle(self.sap_model.SetModelIsLocked(lock_it))
357    
358    
359    def set_present_units(self, units : etabs.eUnits):
360        """Sets the display (present) units.
361
362        :param units: Units enumeration to set.
363        :type units: eUnits
364        """
365        handle(self.sap_model.SetPresentUnits(units))
366
367
368    def set_present_units_components(self, force_units : etabs.eForce, length_units : etabs.eLength, temperature_units : etabs.eTemperature):
369        """Specifies the units for the model.
370
371        :param force_units: Force enumeration to set
372        :type force_units: eForce
373        :param length_units: Length enumeration to set
374        :type length_units: eLength
375        :param temperature_units: Temperature enumeration to set
376        :type temperature_units: eTemperature
377        """
378        handle(self.sap_model.SetPresentUnits_2(force_units, length_units, temperature_units))

pytabs ETABS Model Object EtabsObject 🏢.

All interfaces and enumerations to the Etabs model objects are accessed as properties - refer below.

EtabsModel( attach_to_instance: bool = True, specific_etabs: bool = False, specific_etabs_path: Union[str, pathlib.Path] = '', model_path: Union[str, pathlib.Path] = '', remote_computer: str = '')
 62    def __init__(self,
 63                 attach_to_instance : bool = True,
 64                 specific_etabs : bool = False,
 65                 specific_etabs_path : Union[str, Path] = '',
 66                 model_path : Union[str, Path] = '',
 67                 remote_computer : str = '') -> None:
 68        
 69        # relate ETABS interfaces
 70        self.analyse : Analyse
 71        """EtabsModel `Analyse` interface."""
 72        self.analysis_results_setup : AnalysisResultsSetup
 73        """EtabsModel `AnalysisResultsSetup` interface."""
 74        self.analysis_results : AnalysisResults
 75        """EtabsModel `AnalysisResults` interface."""
 76        self.area_elm : AreaElm
 77        """EtabsModel `AreaElm` interface."""
 78        self.area_obj : AreaObj
 79        """EtabsModel `AreaObj` interface."""
 80        # individual case interfaces to be accessed via LoadCase interface
 81        self.combo : Combo
 82        """EtabsModel `Combo` interface."""
 83        self.constraint : Constraint
 84        """EtabsModel `Constraint` interface."""
 85        self.database_tables : DatabaseTables
 86        """EtabsModel `DatabaseTables` interface."""
 87        self.diaphragm : Diaphragm
 88        """EtabsModel `Diaphragm` interface."""
 89        self.frame_obj : FrameObj
 90        """EtabsModel `FrameObj` interface."""
 91        self.grid_sys : GridSys
 92        """EtabsModel `GridSys` interface."""
 93        self.group : Group
 94        """EtabsModel `Group` interface."""
 95        self.line_elm : LineElm
 96        """EtabsModel `LineElm` interface."""
 97        self.link_obj : LinkObj
 98        """EtabsModel `LinkObj` interface."""
 99        self.load_cases : LoadCases
100        """EtabsModel `LoadCases` interface."""
101        self.load_patterns : LoadPatterns
102        """EtabsModel `LoadPatterns` interface."""
103        self.point_elm : PointElm
104        """EtabsModel `PointElm` interface."""
105        self.point_obj : PointObj
106        """EtabsModel `PointObj` interface."""
107        self.pier_label : PierLabel
108        """EtabsModel `PierLabel` interface."""
109        # individual prop interfaces to be accessed via Property interface
110        self.property : Property
111        """EtabsModel `Property` interface."""
112        self.select : Select
113        """EtabsModel `Select` interface."""
114        self.spandrel_label : SpandrelLabel
115        """EtabsModel `SpandrelLabel` interface."""
116        self.story : Story
117        """EtabsModel `Story` interface."""
118        self.tendon_obj : TendonObj
119        """EtabsModel `TendonObj` interface."""
120        self.tower : Tower
121        """EtabsModel `Tower` interface."""
122        self.view : View
123        """EtabsModel `View` interface."""
124        
125        # relate ETABS cross interface enumerations
126        self.eAreaDesignOrientation = etabs.eAreaDesignOrientation
127        """EtabsModel `AreaDesignOrientation` enumeration."""
128        self.eForce = etabs.eForce
129        """EtabsModel `Force` enumeration."""
130        self.eFrameDesignOrientation = etabs.eFrameDesignOrientation
131        """EtabsModel `FrameDesignOrientation` enumeration."""
132        self.eItemType = etabs.eItemType
133        """EtabsModel `ItemType` enumeration"""
134        self.eItemTypeElm = etabs.eItemTypeElm
135        """EtabsModel `ItemTypeElm` enumeration"""
136        self.eLength = etabs.eLength
137        """EtabsModel `Length` enumeration."""
138        self.eLoadPatternType = etabs.eLoadPatternType
139        """EtabsModel `LoadPatternType` enumeration"""
140        self.eObjType = etabs.eObjType
141        """EtabsModel `ObjType` enumeration"""
142        self.eTemperature = etabs.eTemperature
143        """EtabsModel `Temperature` enumeration."""
144        self.eUnits = etabs.eUnits
145        """EtabsModel `Units` enumeration."""
146        
147        # relate pyTABS custom enumerations
148        self.eFrameDesignProcedure = eFrameDesignProcedure
149        
150        # EtabsModel initial properties
151        self.pytabs_config = pytabs_config
152        """pyTABS config file (pytabs_config.ini)"""
153        self.active : bool = False
154        """`True` if EtabsModel is active, otherwise `False`."""
155        self.model_open : bool = False
156        """`True` if model open, otherwise `False`."""
157        self.model_path : Union[str, Path] = ''
158        """Etabs model filepath."""
159        
160        # create ETABS API helper interface and try to initialise EtabsObject
161        helper = etabs.cHelper(etabs.Helper())
162        if attach_to_instance:
163            # attach to a running instance of ETABS
164            try:
165                # get the active ETABS object        
166                if remote_computer:
167                    self.etabs_object = etabs.cOAPI(helper.GetObjectHost(remote_computer, "CSI.ETABS.API.ETABSObject"))
168                else:
169                    self.etabs_object = etabs.cOAPI(helper.GetObject("CSI.ETABS.API.ETABSObject"))
170                self.active = True
171            except:
172                raise EtabsError(-1, "No running instance ETABS found or failed to attach.")
173        else:
174            if specific_etabs:
175                try:
176                    # create an instance of the ETABS object from the specified path
177                    if remote_computer:
178                        self.etabs_object = etabs.cOAPI(helper.CreateObjectHost(remote_computer, str(specific_etabs_path)))
179                    else:
180                        self.etabs_object = etabs.cOAPI(helper.CreateObject(str(specific_etabs_path)))
181                    self.active = True
182                except :
183                    raise EtabsError(-1, f"Cannot start a new instance of the ETABS from {str(specific_etabs_path)}")
184            else:
185                try: 
186                    # create an instance of the ETABS object from the latest installed ETABS
187                    if remote_computer:
188                        self.etabs_object = etabs.cOAPI(helper.CreateObjectProgIDHost(remote_computer, "CSI.ETABS.API.ETABSObject"))
189                    else:
190                        self.etabs_object = etabs.cOAPI(helper.CreateObjectProgID("CSI.ETABS.API.ETABSObject"))
191                    self.active = True
192                except:
193                    raise EtabsError(-1, "Cannot start a new instance of ETABS.")
194            # start etabs application
195            self.etabs_object.ApplicationStart()
196        
197        # if EtabsObject active 
198        if self.active:
199            # create SapModel interface
200            self.sap_model = etabs.cSapModel(self.etabs_object.SapModel)
201            """EtabsModel `SapModel` interface."""
202            # create File interface
203            self.file = etabs.cFile(self.sap_model.File)
204            
205            # relate external pyTABS interfaces
206            self.analyse = Analyse(self.sap_model)
207            self.analysis_results_setup = AnalysisResultsSetup(self.sap_model)
208            self.analysis_results = AnalysisResults(self.sap_model)
209            self.area_elm = AreaElm(self.sap_model)
210            self.area_obj = AreaObj(self.sap_model)
211            # individual case interfaces to be accessed via LoadCase interface
212            self.combo = Combo(self.sap_model)
213            self.constraint = Constraint(self.sap_model)
214            self.database_tables = DatabaseTables(self.sap_model)
215            self.diaphragm = Diaphragm(self.sap_model)
216            self.frame_obj = FrameObj(self.sap_model)
217            self.grid_sys = GridSys(self.sap_model)
218            self.group = Group(self.sap_model)
219            self.line_elm = LineElm(self.sap_model)
220            self.link_obj = LinkObj(self.sap_model)
221            self.load_cases = LoadCases(self.sap_model)
222            self.load_patterns = LoadPatterns(self.sap_model)
223            self.pier_label = PierLabel(self.sap_model)
224            # individual property interfaces to be accessed via Property interface
225            self.property = Property(self.sap_model)
226            self.select = Select(self.sap_model)
227            self.spandrel_label = SpandrelLabel(self.sap_model)
228            self.story = Story(self.sap_model)
229            self.tendon_obj = TendonObj(self.sap_model)
230            self.tower = Tower(self.sap_model)
231            self.view = View(self.sap_model)
232
233            # if not attached to instance and model path supplied open model
234            if (not attach_to_instance) and model_path:
235                self.open_model(model_path)

EtabsModel Analyse interface.

EtabsModel AnalysisResultsSetup interface.

EtabsModel AnalysisResults interface.

EtabsModel AreaElm interface.

EtabsModel AreaObj interface.

EtabsModel Combo interface.

EtabsModel Constraint interface.

EtabsModel DatabaseTables interface.

EtabsModel Diaphragm interface.

EtabsModel FrameObj interface.

EtabsModel GridSys interface.

EtabsModel Group interface.

EtabsModel LineElm interface.

EtabsModel LoadCases interface.

EtabsModel LoadPatterns interface.

EtabsModel PointElm interface.

EtabsModel PointObj interface.

EtabsModel PierLabel interface.

EtabsModel Property interface.

EtabsModel Select interface.

EtabsModel SpandrelLabel interface.

EtabsModel Story interface.

EtabsModel TendonObj interface.

EtabsModel Tower interface.

EtabsModel View interface.

eAreaDesignOrientation

EtabsModel AreaDesignOrientation enumeration.

eForce

EtabsModel Force enumeration.

eFrameDesignOrientation

EtabsModel FrameDesignOrientation enumeration.

eItemType

EtabsModel ItemType enumeration

eItemTypeElm

EtabsModel ItemTypeElm enumeration

eLength

EtabsModel Length enumeration.

eLoadPatternType

EtabsModel LoadPatternType enumeration

eObjType

EtabsModel ObjType enumeration

eTemperature

EtabsModel Temperature enumeration.

eUnits

EtabsModel Units enumeration.

pytabs_config

pyTABS config file (pytabs_config.ini)

active: bool

True if EtabsModel is active, otherwise False.

model_open: bool

True if model open, otherwise False.

model_path: Union[str, pathlib.Path]

Etabs model filepath.

def exit_application(self):
238    def exit_application(self):
239        '''Terminates ETABS application severing API connection'''
240        self.etabs_object.ApplicationExit(False)
241        self.model_open = False
242        self.model_path = ''
243        self.sap_model = None
244        self.active = False

Terminates ETABS application severing API connection

def open_model(self, model_path: Union[str, pathlib.Path]) -> None:
247    def open_model(self, model_path: Union[str, Path]) -> None:
248        """Opens ETABS model file.
249
250        :param model_path: file path to ETABS model file
251        :type model_path: Union[str, Path]
252        """
253        handle(self.file.OpenFile(str(model_path)))
254        self.model_path = model_path
255        self.model_open = True

Opens ETABS model file.

Parameters
  • model_path: file path to ETABS model file
def new_model(self, new_model_path: Union[str, pathlib.Path]) -> None:
258    def new_model(self, new_model_path: Union[str, Path]) -> None:
259        """Creates new blank ETABS model and saves.
260
261        :param new_model_path: file path to save new blank ETABS model file
262        :type new_model_path: Union[str, Path]
263        """
264        handle(self.file.NewBlank())
265        handle(self.file.Save(str(new_model_path)))
266        self.model_path = new_model_path
267        self.model_open = True

Creates new blank ETABS model and saves.

Parameters
  • new_model_path: file path to save new blank ETABS model file
def get_database_units(self) -> ETABSv1.eUnits:
270    def get_database_units(self) -> etabs.eUnits:
271        """Returns a value from the eUnits enumeration indicating the database units for the model.
272        All data is internally stored in the model in these units and converted to the present units as needed.
273
274        :raises EtabsError: Database units could not be returned
275        :return: Units enumeration
276        :rtype: eUnits
277        """
278        self.sap_model.GetDatabaseUnits()
279        if ret == 0:
280            raise EtabsError(0, "Database units could not be returned.")
281        else:
282            return ret

Returns a value from the eUnits enumeration indicating the database units for the model. All data is internally stored in the model in these units and converted to the present units as needed.

Raises
  • EtabsError: Database units could not be returned
Returns

Units enumeration

def get_database_units_components(self) -> pytabs.model.UnitsComponents:
285    def get_database_units_components(self) -> UnitsComponents:
286        """Retrieves the database units for the model.
287        All data is internally stored in the model in these units and converted to the present units as needed.
288
289        :return: units for force, length and temperature units
290        :rtype: UnitsComponents
291        """
292        force_units = etabs.eForce.NotApplicable
293        length_units = etabs.eLength.NotApplicable
294        temperature_units = etabs.eTemperature.NotApplicable
295        [ret, force_units, length_units, temperature_units] =  self.sap_model.GetDatabaseUnits_2(force_units, length_units, temperature_units)
296        handle(ret)
297        return {'force_units': force_units,
298                'length_units': length_units,
299                'temperature_units': temperature_units}

Retrieves the database units for the model. All data is internally stored in the model in these units and converted to the present units as needed.

Returns

units for force, length and temperature units

def get_model_is_locked(self) -> bool:
302    def get_model_is_locked(self) -> bool:
303        """Retrieves locked status of the model.
304
305        :return: True if model is looked, otherwise False
306        :rtype: bool
307        """
308        return self.sap_model.GetModelIsLocked()

Retrieves locked status of the model.

Returns

True if model is looked, otherwise False

def get_present_coord_system(self) -> str:
311    def get_present_coord_system(self) -> str:
312        """Retrieves model present coordinate system.
313
314        :return: name of coordinate system
315        :rtype: str
316        """
317        return self.sap_model.GetPresentCoordSystem()

Retrieves model present coordinate system.

Returns

name of coordinate system

def get_present_units(self) -> ETABSv1.eUnits:
320    def get_present_units(self) -> etabs.eUnits:
321        """Returns a value from the eUnits enumeration indicating the units presently specified for the model.
322
323        :raises EtabsError: Present units could not be returned
324        :return: Units enumeration
325        :rtype: eUnits
326        """
327        ret = self.sap_model.GetPresentUnits()
328        if ret == 0:
329            raise EtabsError(0, "Present units could not be returned.")
330        else:
331            return ret

Returns a value from the eUnits enumeration indicating the units presently specified for the model.

Raises
  • EtabsError: Present units could not be returned
Returns

Units enumeration

def get_present_units_components(self) -> pytabs.model.UnitsComponents:
334    def get_present_units_components(self) -> UnitsComponents:
335        """Retrieves the units presently specified for the model.
336
337        :return: units components for force, length and temperature units
338        :rtype: UnitsComponents
339        """
340        force_units = etabs.eForce.NotApplicable
341        length_units = etabs.eLength.NotApplicable
342        temperature_units = etabs.eTemperature.NotApplicable
343        [ret, force_units, length_units, temperature_units] =  self.sap_model.GetPresentUnits_2(force_units, length_units, temperature_units)
344        handle(ret)
345        return {'force_units': force_units,
346                'length_units': length_units,
347                'temperature_units': temperature_units}

Retrieves the units presently specified for the model.

Returns

units components for force, length and temperature units

def set_model_is_locked(self, lock_it: bool = True):
350    def set_model_is_locked(self, lock_it : bool = True):
351        """Locks or unlocks the model.
352
353        :param lock_it: True to lock mode, False to unlock, defaults to True
354        :type lock_it: bool, optional
355        """
356        handle(self.sap_model.SetModelIsLocked(lock_it))

Locks or unlocks the model.

Parameters
  • lock_it: True to lock mode, False to unlock, defaults to True
def set_present_units(self, units: ETABSv1.eUnits):
359    def set_present_units(self, units : etabs.eUnits):
360        """Sets the display (present) units.
361
362        :param units: Units enumeration to set.
363        :type units: eUnits
364        """
365        handle(self.sap_model.SetPresentUnits(units))

Sets the display (present) units.

Parameters
  • units: Units enumeration to set.
def set_present_units_components( self, force_units: ETABSv1.eForce, length_units: ETABSv1.eLength, temperature_units: ETABSv1.eTemperature):
368    def set_present_units_components(self, force_units : etabs.eForce, length_units : etabs.eLength, temperature_units : etabs.eTemperature):
369        """Specifies the units for the model.
370
371        :param force_units: Force enumeration to set
372        :type force_units: eForce
373        :param length_units: Length enumeration to set
374        :type length_units: eLength
375        :param temperature_units: Temperature enumeration to set
376        :type temperature_units: eTemperature
377        """
378        handle(self.sap_model.SetPresentUnits_2(force_units, length_units, temperature_units))

Specifies the units for the model.

Parameters
  • force_units: Force enumeration to set
  • length_units: Length enumeration to set
  • temperature_units: Temperature enumeration to set