Sap2000 Api

CRÍTICO: Esto es lo opuesto de lo que sugiere la firma VBA. El COM bridge en Python siempre coloca el Long return code al final.

# Ejemplo: AddCartesian retorna [Name_out, ret_code]
raw = SapModel.PointObj.AddCartesian(5, 3, 2, "", "PT1")
point_name = raw[0]   # ByRef Name output (primero)
ret_code   = raw[-1]  # return code (último)
assert ret_code == 0, f"AddCartesian failed: {ret_code}"

# Ejemplo: GetCoordCartesian retorna [x, y, z, ret_code]
coord = SapModel.PointObj.GetCoordCartesian(point_name, 0, 0, 0)
x, y, z = coord[0], coord[1], coord[2]
ret_code = coord[-1]

# Ejemplo: FrameObj.GetPoints retorna [pt_i, pt_j, ret_code]
raw = SapModel.FrameObj.GetPoints(frame_name, "", "")
pt_i = raw[0]
pt_j = raw[1]
ret_code = raw[-1]

Patrón seguro universal:

raw = SapModel.SomeObj.SomeFunction(...)
ret_code = raw[-1] if isinstance(raw, (list, tuple)) else raw
assert ret_code == 0, f"SomeFunction failed: {ret_code}"

Layouts ByRef Verificados

Template Básico de Script

# Siempre trabajar a través de SapModel — ya está conectado
ret = SapModel.InitializeNewModel()
ret = SapModel.File.NewBlank()

# Definir materiales
ret = SapModel.PropMaterial.SetMaterial("CONC", 2)  # 2 = Concrete
ret = SapModel.PropMaterial.SetMPIsotropic("CONC", 3600, 0.2, 0.0000055)

# Definir secciones
ret = SapModel.PropFrame.SetRectangle("R1", "CONC", 12, 12)

# Crear geometría
raw = SapModel.FrameObj.AddByCoord(0, 0, 0, 0, 0, 120, "", "R1", "1")
frame_name = raw[0]
assert raw[-1] == 0, f"AddByCoord failed: {raw[-1]}"

# Guardar modelo en directorio temporal
ret = SapModel.File.Save(sap_temp_dir + r"\my_model.sdb")
assert ret == 0, f"File.Save failed: {ret}"

# Escribir resultados para verificación
result["frame_name"] = frame_name
result["num_frames"] = SapModel.FrameObj.Count()

Template de Extracción de Resultados

# Guardar modelo antes de análisis
ret = SapModel.File.Save(sap_temp_dir + r"\my_model.sdb")
assert ret == 0, f"File.Save failed: {ret}"

# Seleccionar caso de carga para output
ret = SapModel.Results.Setup.DeselectAllCasesAndCombosForOutput()
ret = SapModel.Results.Setup.SetCaseSelectedForOutput("DEAD")

# Obtener desplazamientos de nudo
raw = SapModel.Results.JointDispl(
    "1",      # Nombre del nudo
    0,        # eItemTypeElm_ObjectElm
    0, [], [], [], [], [], [], [], [], [], []
)
# raw[-1] es SIEMPRE el return code
ret_code = raw[-1]
result["displacement_U3"] = raw[8][0] if ret_code == 0 and len(raw[8]) > 0 else None

Function Registry

El registry (scripts/registry.json) rastrea qué funciones API han sido testeadas exitosamente. Usar para evitar re-descubrir firmas y convenciones ByRef.

Consultar el Registry

# Verificar si una función específica ha sido verificada:
query_function_registry(function_path="SapModel.FrameObj.AddByCoord")

# Buscar por keyword:
query_function_registry(query="frame")

# Solo funciones verificadas:
query_function_registry(verified_only=True)

# Resumen del registry:
query_function_registry()

Wrapper Scripts

Los wrappers verificados viven en scripts/wrappers/ y demuestran el uso correcto. Cada wrapper:

• Apunta a una sola función API
• Es auto-contenido (inicializa un modelo fresco)
• Documenta el layout ByRef de outputs
• Valida con asserts y escribe a result

El wrapper es la única fuente de verdad para esa función. El conteo de argumentos, orden, y layout de retorno mostrados en el wrapper han sido verificados contra el COM bridge live de SAP2000.

Workflow para usar un wrapper:

1. query_function_registry(function_path="SapModel.X.Y") → verificar wrapper_script
2. Si existe: load_script("func_X_Y") → copiar la llamada verbatim
3. Solo si no existe: consultar search_api_docs y marcar como no verificado

Auto-Registro

Cuando un script se ejecuta exitosamente via run_sap_script, todas las funciones API usadas se detectan y registran automáticamente como verificadas. La respuesta incluye una lista registered_functions mostrando lo capturado.

Dos Caminos de Registro

Jerarquía: wrapper > manual > auto

Campos del Registry

Naming Convention de Wrappers

API:     SapModel.FrameObj.AddByCoord
Wrapper: func_FrameObj_AddByCoord.py
Regla:   Quitar "SapModel.", reemplazar "." por "_", prepend "func_"

Unidades

Establecer unidades ANTES de crear geometría:

ret = SapModel.SetPresentUnits(6)  # kN_m_C

Para la lista completa de enumeraciones (eUnits, eMatType, eLoadPatternType, etc.) → ver enum-reference.md.

Arrays

• 0-based en todos los casos
• Al pasar arrays a COM, usar listas de Python
• Arrays dinámicos en output: COM los llena y retorna en la tupla

Modificadores de Sección Frame

Array de 8 valores (índices 0–7):

ModValue = [1000, 0, 0, 1, 1, 1, 1, 1]
# [0]=Area, [1]=AS2, [2]=AS3, [3]=Torsion, [4]=I22, [5]=I33, [6]=Mass, [7]=Weight
ret = SapModel.PropFrame.SetModifiers("R1", ModValue)

Errores Comunes y Soluciones

Para reglas operacionales completas (DO/DON'T), ver el agente @sap2000-scripter.

Jerarquía de Objetos

SapObject (cOAPI)
├── ApplicationStart()
├── ApplicationExit(save)
├── GetOAPIVersionNumber()
└── SapModel (cSapModel)
    ├── InitializeNewModel()
    ├── SetPresentUnits(units)
    ├── GetPresentUnits()
    ├── File
    │   ├── NewBlank()
    │   ├── New2DFrame(type, stories, height, bays, width)
    │   ├── New3DFrame(type, stories, height, baysX, widthX, baysY, widthY)
    │   ├── Save(path)
    │   └── OpenFile(path)
    ├── PropMaterial
    │   ├── SetMaterial(name, type)
    │   └── SetMPIsotropic(name, E, poisson, thermal)
    ├── PropFrame
    │   ├── SetRectangle(name, material, depth, width)
    │   └── SetModifiers(name, value_array)
    ├── FrameObj
    │   ├── AddByCoord(x1,y1,z1, x2,y2,z2, name, section, group)
    │   ├── GetPoints(name) → [point1, point2, ret_code]
    │   ├── Count() → int
    │   ├── SetLoadDistributed(name, pattern, type, dir, dist1, dist2, val1, val2)
    │   └── SetLoadPoint(name, pattern, type, dir, dist, val)
    ├── AreaObj
    │   ├── AddByCoord(nPoints, x[], y[], z[], name, prop)
    │   ├── AddByPoint(nPoints, points[], name, prop)
    │   └── Count() → int
    ├── PointObj
    │   ├── SetRestraint(name, restraint_array)
    │   ├── SetLoadForce(name, pattern, value_array)
    │   └── Count() → int
    ├── LoadPatterns
    │   └── Add(name, type, selfMassMultiplier)
    ├── LoadCases
    │   └── ChangeName(old, new)
    ├── RespCombo
    │   └── Add(name, comboType)
    ├── Analyze
    │   ├── RunAnalysis()
    │   ├── CreateAnalysisModel()
    │   └── DeleteResults(name, all)
    ├── Results
    │   ├── Setup
    │   │   ├── DeselectAllCasesAndCombosForOutput()
    │   │   └── SetCaseSelectedForOutput(name)
    │   └── JointDispl(name, itemType, ...) → [NRes, Obj[], Elm[], LC[], StType[], StNum[], U1[], U2[], U3[], R1[], R2[], R3[], ret_code]
    ├── View
    │   └── RefreshView(window, zoom)
    └── SelectObj
        ├── All()
        └── ClearSelection()

Archivos de Referencia

Para información detallada, cargar estos archivos bajo demanda:

• Patrones API — Patrones detallados para operaciones comunes
• Workflows Comunes — Pasos para tareas típicas
• Referencia de Enumeraciones — Valores completos de enums
• Templates de Scripts — Templates paramétricos reutilizables
• Generación de GUI — Guía para generar GUI standalone