More in this chapter:


An API wrapper is a file containing different call functions to make it easier to create the model and run the analysis. The wrapper below is created for python. Please see a detailed description in the documentation below.

Note: This is just an example of a wrapper. You are of course able to create a wrapper file yourself or make changes in the wrapper to fit your project or situation with regard to input values and different call functions. For further information about this, please visit the section Customize the wrapper.

API-wrapper for python

The following information is valid for python. However, it is possible to construct a similar wrapper for other programming languages.

 

Getting started

First, download the wrapper and put the files into a folder. Please ensure that there are no special signs in the path to the folder. To get started, please check that the paths found inside the wrapper are correct for the "Database dir" and "Installation dir".

Download⭳ API-wrapper (zip)

1556029928168-186.png

Now you are ready to open a new python file in the same folder as the wrapper. Import the wrapper with the import function:

Import fdAPI_wrapper as fd

You can use a shortcut name to access the imported library of functions. In this example we use "fd". All functions and classes are now accessible by writing fd.<function>. For example fd.initiateModel('S').

Classes

coord

class coord:
   def ___init___(self, x=0, y=0, z=0):
      self.x = x
      self.y = y
      self.z = z

This class is used to define coordinates.
coord.x - x
coord.y - y
coord.z - z

XML

class XML:
   def ___init___(self, filename = '', batch = '', export = ''):
      self.filename = filename
      self.batch = batch
      self.export = export

This class is used to define the different file paths and names for the model file, batch export and csv output. The base folder is the place of the wrapper.

XML.filename - path and filename of model file
XML.batch - path and filename of the batch export file
XML.export - path and filename of the csv output from batch file

material

class material:
   def ___init___(self, type = '', creep = '', shrinkage = ''):
      self.type = type
      self.creep = creep
      self.shrinkage = shrinkage

This class is used to define material parameters. It is used as input parameter when creating a material in the XML model file.

material.type - material name as string

ConcreteC12/15C16/20C20/25C25/30C28/35C30/37C32/40C35/45C40/50C45/55C50/60C54/65C55/67C58/70C60/75C70/85C80/95C90/105
SteelS235S275S355S420S450S460
TimberC14C16C18C20C22C24C27C30C35C40C45C50D18D24D30D35D40D50
 D60D70L40sL40cGL 20hGL 22hGL 24hGL 26hGL 28hGL 30hGL 32hGL 36hGL 20cGL 22cGL 24cGL 26cGL 28cGL 30c
 GL 32cGL 36c                

Service class 1 is assumed for all timber materials. 

material.creep - creep for concrete
material. shrinkage - shrinkage for concrete

Functions

initiateModel

initiateModel(annex)

Use this function to initiate the base template for the XML model file. This needs to be done first before adding elements to the XML file.

annex - The selected annex for the model as a string

'GB' - Brittish'DK' - Danish'FIN' - Finnish
'D' - German'H' - Hungarian

'N' - Norwegian

'PL' - Polish'RO' - Romanian'S' - Swedish

finish

finish(filename)

This function will save and write the XML model file to the disk. It will also sort and indent the XML-file so that FEM-Design can read it. This function has to be ran before the file can be opened in FEM-Design.

filename - The location and filename of the XML file as a string, for example: 'C:\\temp\\example.struxml'

addMaterial

addMaterial(material)
return material_ID

This function will add a material to the XML model file. The return value is used to assign the material to different objects.

material - The material to be added as a material class object. Please see above: class: material

addSection

addSection(section, eccentricity)
return section_INFO

This function will add a section to the XML model file. The return value is used to assign the specific section to different objects. The section names can be found in this list: Section names

section - This is the section name as a string
eccentricity - The eccentricity of the section as a coord object, see class: coord.

addBeam

addBeam(section_INFO, material_ID, point1, point2, rotation, release)

This function will add a beam object to the XML model file. The beam is added as a line between two points, point1 and point2. 

section_INFO - The section of the beam. Return value from the addSection function
material_ID - Material for the beam. Return value from the addMaterial function
point1 - Coordinate for the first point as a coord object, see class: coord
point2 - Coordinate for the second point as a coord object, see class: coord
rotation - Rotation of the beam in degrees
release - The end releases of the beam as a string: 'hinged' or 'fixed'

addColumn

addColumn(section_INFO, material_ID, point1, height, rotation, release)

This function will add a column object to the XML model file. The column is inserted in a point with a specified height.

section_INFO - The section of the column. Return value from the addSection function
material_ID - Material for the beam. Return value from the addMaterial function
point1 - Coordinate for the insertion point of the column as a coord object, see class: coord
height - Height of the column in meters
rotation - Rotation of the column in degrees
release - The end releases of the column as a string: 'hinged' or 'fixed'

addTruss

addTruss(section_INFO, material_ID, point1, point2)

This function will add a truss object to the XML model file. The truss is added as a line between two points.

section_INFO - The section of the truss. Return value from the addSection function
material_ID - Material for the truss. Return value from the addMaterial function
point1 - Coordinate for the first point as a coord object, see class: coord
point2 - Coordinate for the second point as a coord object, see class: coord

addPlate

addPlate(material_ID, thickness, release, point1, point2)

This function will add a plate as a rectangle with constant thickness to the XML model file. The release setting is set for all the edges of the plate.

material_ID - Material for the plate. Return value from the addMaterial function
thickness - Thickness of the plate in meters
release - The edge releases of the plate as a string: 'hinged' or 'fixed'
point1 - Coordinate for the first point of the rectangle as a coord object, see class: coord
point2 - Coordinate for the second point of the rectangle as a coord object, see class: coord

addPlateComplex

addPlateComplex(material_ID, thickness, release, *points)

This function will add a plate with arbitrary shape defined by a series of lines to the XML model file. The plate is defined with constant thickness. The release setting is set for all the edges of the plate.

material_ID - The material of the plate. Return value from the addMaterial function
thickness - Thickness of the plate in meters
release - The edge releases of the plate as a string 'hinged' or 'fixed'
p1, p2, p3... pi - As many point input parameters as needed. Straight lines will be defined between the different points and between the first and last point. The coordinates defined with coord object, see class coord

1556012847391-857.png

addWall

addWall(material_ID, thickness, release, point1, point2)

This function will add a wall object as a rectangle with constant thickness to the XML model file. The release setting is set for all the edges of the wall.

material_ID - Material for the wall. Return value from the addMaterial function
thickness - Thickness of the wall in meters
release - The edge releases of the wall as a string: 'hinged' or 'fixed'
point1 - Coordinate for the first point of the rectangle as a coord object, see class: coord
point2 - Coordinate for the second point of the rectangle as a coord object, see class: coord

addPointSupport

addPointSupport(point, type)

This function will add a point support in the specified point to the XML model file. 

point - Coordinate for the point support defined as a coord object, see class: coord
type - The type of the support as a string: 'hinged' or 'fixed'

addLineSupport

addLineSupport(point1, point2, type)

This function will add a line support as a line between the defined coordinates to the XML model file.

point1 - Coordinate for the first point as a coord object, see class: coord
point2 - Coordinate for the second point as a coord object, see class: coord
type - The type of the support as a string: 'hinged' or 'fixed'

addSurfaceSupport

addSurfaceSupport(point1, point2)

This function will add a surface support as a rectangle to the XML model file. The support will be 'rigid' in x, y and z translation. 

point1 - Coordinate for the first point of the rectangle as a coord object, see class: coord
point2 - Coordinate for the second point of the rectangle as a coord object, see class: coord

addCover

addCover(point1, point2)

This function will add a cover object as a rectangle between two points.

point1 - Coordinate for the first point of the rectangle as a coord object, see class: coord
point2 - Coordinate for the second point of the rectangle as a coord object, see class: coord

addLoadCase

addLoadCase(name, selfWeight)
return loadCaseID

This function will add a load case to the XML model file and return a load case ID which is used to assign different loads to a specific load case.

name - The name of the load case
selfWeight - If the program should generate self-weight of the modeled objects or not, input value: True or False

addLoadComb

addLoadComb(nameLoadComb, type, loadCaseList, gammaLoadCases)

This function will add a load combination to the XML model file. 

nameLoadComb - Name of the load combination
type - The type of the load combination as a string

Type
 UUaUsSqSfSc

loadCaseList - List of load cases to be included in the load combination, return value of addLoadCase (loadCaseID)
gammaLoadCases - List of gamma values for the corresponding load cases

addPointLoad

addPointLoad(force, direciton, loadCase, point)

This function will add a point load to the XML model file. 

force - The magnitude of the point load in kilo newtons
direction - The direction of the point load as a coord object, see class: coord
loadCase - The load case (loadCaseID) for the point load, return value from the addLoadCase function
point - Coordinate of the point load as a coord object, see class: coord

addLineLoad

addLineLoad(point1, point2, force, direction, loadCase, point1, point2)

This function will add a line load between two points to the XML model file.

force - The magnitude of the line load in kilo newtons per meter
direction - The direction of the line load as a coord object, see class: coord
loadCase - The load case (loadCaseID) for the line load, return value from the addLoadCase function
point1 - Coordinate of the first point as a coord object, see class: coord
point2 - Coordinate of the second point as a coord object, see class: coord

addSurfaceLoad

addSurfaceLoad(force, direction, loadCase, point1, point2)

This function will add a surface load as a rectangle between two points to the XML model file.

force - The magnitude of the surface load in kilo newtons per square meter
direction - The direction of the surface load as a coord object, see class: coord
loadCase - The load case (loadCaseID) for the surface load, return value from the addLoadCase function
point1 - Coordinate of the first point as a coord object, see class: coord
point2 - Coordinate of the second point as a coord object, see class: coord

openFD

openFD(filename)

This function will open FEM-Design and the selected file.

filename - The filename and path from the working folder to the XML model file.

runFD

runFD(analysis, save, close, design, filename, batchfile = '', exportfile = '')

This function will open FEM-Design and execute a script file which is build depending on the input parameters of the function.

analysis - Analysis type as a string, choose from 'LIN', 'NLE', 'NLE+PL', 'CR', '2ND', 'STAB' and 'IMP'
save - Save the model and result file or not, input: True or False
close - Close FEM-Design after the analysis is finished, input: True or False
design - Perform design check for steel, timber or concrete as a string: 'steel', 'RC', 'timber, or 'no'
filename - Name and path of the model from the working folder
batchfile - Name and path of the batchfile from the working folder (optional)
exportfile - Name and path of the export file from the working folder (optional)
 

Customize the wrapper

The provided wrapper file is an example of how a wrapper file can look. It is of course possible to customize the wrapper to fit the specific needs of the project or workflow. The example wrapper provided in this wiki is limited in many ways to make it easy and fast to access the settings of the different object. If the user can modify the wrapper to unlock more settings for the different objects or add objects that are missing in the current version of the wrapper. 

The wrapper file is build by different functions, one for each object to be added. In addition to this, some useful help-functions are also included. It is important to understand the help functions and what they do before changing the wrapper.

Help functions

These functions are used to generate information in an effective way in the wrapper file. When there is an operation performed multiple times, it is generally made as a help-function. Below the different help functions is described in more detail.

ID

ID(type)
return "X.X"

This function will keep track of the different littera used for the different objects. For example, if a beam is to be added, the function will return "B.<X>" where "X" is the number of the beam starting from 1.

type - The type of the object as a string

genGUID

genGUID()
return GUID

This function will generate and return a GUID as a string.

genUTC

genUTC()
return UTC

This function will generate the time and date in the correct format for the struXML file and return it as a string.

nmz

nmz(v)
return normalized

This function will normalize a vector.

- A vector in 3D

normal

normal(point1, point2, rot)
return normal_vector

This function will calculate the normal vector to a plane defined by three points. Point 1, point 2 and point1.z + 1.

point1 - Point 1 as a coord-object
point2 - Point 2 as a coord-object
rot - Rotation in degrees

Change the input parameters of a function

Open the wrapper file and go to the specific function. Change the input values of the function and add the input that is needed and add it to the XML creation part of the function. In this example we will add the possibility to set different end releases to the two ends of the beam object.

1. First find the beam object and add the input of another release.

def addBeam(section_INFO, material_ID, point1, point2, rotation, release_start, release_end):

2. Identify the part of the wrapper that sets the end conditions of the beam.

if release == 'hinged':
     ET.SubElement(add_beam_child, 'connectivity', m_x='true', m_y='true', m_z='true', r_x='true', r_y='false', r_z='false')
     ET.SubElement(add_beam_child, 'connectivity', m_x='true', m_y='true', m_z='true', r_x='true', r_y='false', r_z='false')
else:
     ET.SubElement(add_beam_child, 'connectivity', m_x='true', m_y='true', m_z='true', r_x='true', r_y='true', r_z='true')
     ET.SubElement(add_beam_child, 'connectivity', m_x='true', m_y='true', m_z='true', r_x='true', r_y='true', r_z='true')

3. Rewrite the if statement to take into consideration the new inputs (there are many ways of writing this with python, this is just a simple and easy way to understand).

if release_start == 'hinged':
     ET.SubElement(add_beam_child, 'connectivity', m_x='true', m_y='true', m_z='true', r_x='true', r_y='false', r_z='false')
     if release_end == 'hinged':
          ET.SubElement(add_beam_child, 'connectivity', m_x='true', m_y='true', m_z='true', r_x='true', r_y='false', r_z='false')
     else:
          ET.SubElement(add_beam_child, 'connectivity', m_x='true', m_y='true', m_z='true', r_x='true', r_y='true', r_z='true')
else:
     ET.SubElement(add_beam_child, 'connectivity', m_x='true', m_y='true', m_z='true', r_x='true', r_y='true', r_z='true')
     if release_end == 'hinged':
          ET.SubElement(add_beam_child, 'connectivity', m_x='true', m_y='true', m_z='true', r_x='true', r_y='false', r_z='false')
     else:
          ET.SubElement(add_beam_child, 'connectivity', m_x='true', m_y='true', m_z='true', r_x='true', r_y='true', r_z='true')

Now the function will take two end release settings and change the XML file accordingly. 

Add a new function to the wrapper

The easiest way of adding new objects to the wrapper is to create them in FEM-Design and save it as struXML. Now study the created XML text to be able to understand it and recreate it. 

It is mainly the command SubElement from the library Element tree that is used to add lines in the XML file. Please visit https://docs.python.org/2/library/xml.etree.elementtree.html for a complete documentation. 

It is also important to sort the XML file. This is done in the function called finish. This will sort the XML file by simply removing and adding the different objects in the XML file in the correct order.


Disclaimer: All example files, wrappers and documentation are for illustrative and educational purposes and may not interact with FEM-Design in a reliable way depending on your version, installation and content of the files. Furthermore, StruSoft won´t guarantee full support of the API functions since they are customizable by the customer.

Tags: API
Created by IwonaBudny on 2019/02/07 13:13
   
Copyright 2019 StruSoft AB
FEM-Design Wiki