Preprocessing

Tcl to Python

opstool.pre.tcl2py(input_file, output_file, prefix='ops', encoding='utf-8', keep_comments=False)

Convert OpenSees Tcl code to OpenSeesPy Python format.

Note

• This function supports Tcl syntax and will flatten your Tcl code, including loops, judgments, assignments, proc, etc.,

• Do not use assignment statements for OpenSees commands, such as set ok [analyze 1], set lambdaN [eigen 10], it will trigger an error! This is because this function does not run the OpenSees command at all.

• If an encoding error is reported, please check the file and delete any special characters that exist, such as some Chinese characters that cannot be encoded.

Parameters

input_filestr

The name of input .tcl file.

output_filestr

The name of output .py file.

prefixstr, optional

prefix name of openseespy, by default ops. I.e., import openseespy.opensees as ops. If None or void str ‘’, the prefix is not used. I.e., from openseespy.opensees import *.

encoding: str, optional

file encoding format, by default “utf-8”.

keep_comments: bool, optional

Comments are preserved, by default False. Note that this parameter will replace all opensees commands in the comment line, if any.

Remove void nodes

opstool.pre.remove_void_nodes()

Removes free node from the model, i.e. nodes that are not attached to any element.

Returns

free_node_tags: list, a list containing all free nodes.

Loads

Load distribution pattern

opstool.pre.apply_load_distribution(node_tags=None, coord_axis='z', load_axis='x', dist_type='triangle', sum_normalized=True, plot=False)

Apply load distribution along specified coordinate axis.

Note

The load is applied to the OpenSeesPy domain. If sum_normalized=True, The sum of the loads for all nodes is 1.0. If sum_normalized=False, The maximum load is set to 1.0.

Parameters:

node_tagslist, tuple, int, optional

The node tags where the load will be applied. If None, the function will apply the load to all nodes.

coord_axisstr, default=’z’

The coordinate axis along which the load is distributed (‘x’, ‘y’, or ‘z’).

load_axisstr, default=’x’

The load direction (‘x’, ‘y’, or ‘z’).

dist_typestr, default=’triangle’

Type of distribution (‘triangle’, “parabola”, ‘half_parabola_concave’, ‘half_parabola_convex’, ‘uniform’).

sum_normalizedbool, default=True

If True, the loads are normalized to ensure their sum is 1.0. If False, the maximum load is set to 1.0.

plotbool, optional

If True, plots the load distribution graph.

Returns:

node_loadsdict

A dictionary containing the node tags and the corresponding normalized loads.

Generate gravity load

opstool.pre.gen_grav_load(exclude_nodes=None, direction='Z', factor=-9.81)

Applying the gravity loads.

Note

The mass values are from nodeMass(nodeTag) command, i.e., ones set in mass() command.

Parameters

exclude_nodes: list, default=None

Excluded node tags, whose masses will not be used to generate gravity loads.

direction: str, default=”Z”

The gravity load direction.

factor: float, default=-9.81

The factor applied to the mass values, it should be the multiplication of gravitational acceleration and directional indicators, e.g., -9.81, where 9.81 is the gravitational acceleration and -1 indicates along the negative Z axis. Of course, it can be multiplied by an additional factor to account for additional constant loads, e.g., 1.05 * (-9.81).

Returns

None

Transform beam uniform and point load from global to local coordinate system

opstool.pre.transform_beam_uniform_load(ele_tags, wx=0.0, wy=0.0, wz=0.0)

Transforms a uniformly distributed beam load from the global coordinate system to the local coordinate system. :rtype: None

Note

This function will automatically call the EleLoad Command to generate element loads. However, you need to create timeSeries and load pattern objects externally in advance. The load generated by this function will belong to the load pattern closest to it.

Parameters

ele_tagsint, list, tuple, np.ndarray

Beam element tags.

wxfloat, list, np.ndarray, default=0.0

Uniformly distributed load in the global X direction. If a list or numpy array is provided, the length should be the same as the number of elements.

wyfloat, list, np.ndarray, default=0.0

Uniformly distributed load in the global Y direction. If a list or numpy array is provided, the length should be the same as the number of elements.

wzfloat, list, np.ndarray, default=0.0

Uniformly distributed load in the global Z direction. If a list or numpy array is provided, the length should be the same as the number of elements.

opstool.pre.transform_beam_point_load(ele_tags, px=0.0, py=0.0, pz=0.0, xl=0.5)

Transforms point loads for beam elements from global to local coordinates.

Return type:

None

Parameters

ele_tagsint, list, tuple, np.ndarray

Beam element tags.

pxfloat, list, np.ndarray, default=0.0

Point load in the global X direction. If a list or numpy array is provided, the length should be the same as the number of elements.

pyfloat, list, np.ndarray, default=0.0

Point load in the global Y direction. If a list or numpy array is provided, the length should be the same as the number of elements.

pzfloat, list, np.ndarray, default=0.0

Point load in the global Z direction. If a list or numpy array is provided, the length should be the same as the number of elements.

xlfloat, list, np.ndarray, default=0.5

The position of the point load along the beam element in a local coord system. If a list or numpy array is provided, the length should be the same as the number of elements.

Transform surface uniform load from local to global coordinate system

opstool.pre.transform_surface_uniform_load(ele_tags, p=0.0)

Converts uniform surface loads into equivalent nodal forces in the global coordinate system. According to the static equivalence principle, the distributed load is equivalent to the node load. :rtype: None

Note

This function will automatically call the NodalLoad Command to generate nodal loads. However, you need to create timeSeries and load pattern objects externally in advance. The load generated by this function will belong to the load pattern closest to it.

Parameters

ele_tagsint, list, tuple, np.ndarray

Surface element tags.

pfloat, list, np.ndarray, default=0.0

Uniform surface load magnitude (per unit area) along the surface normal direction. The positive direction of the normal is obtained by the cross-product of the I-J and J-K edges. If a list or numpy array is provided, the length should be the same as the number of elements.

Model Mass

class opstool.pre.ModelMass

A class used to generate node masses. Element mass is distributed equally to each connected node.

add_node_mass(node_tag, mass)

Add mass to the existing node mass.

Parameters

node_tag: int, node tag. mass: float, mass value.

Returns

None

add_mass_from_line(ele_tags, rho, area)

Add mass from two-node line elements.

Parameters

ele_tags: Union[list, int]

Element tag or list.

rho: Union[list, float]

Mass density or list, if list length shoud same as ele_tags.

area: Union[list, float]

Cross-sectional area or list, if list length shoud same as ele_tags.

add_mass_from_surf(ele_tags, rho, d)

Add mass from a planar element, including shell.

Parameters

ele_tags: Union[list, int]

Element tag or list.

rho: Union[list, float]

Mass density or list, if list length shoud same as ele_tags.

d: Union[list, float]

Element thickness or list, if list length shoud same as ele_tags.

add_mass_from_brick(ele_tags, rho)

Add mass from tetrahedral or hexahedral elements.

Parameters

ele_tags: Union[list, int]

Element tag or list.

rho: Union[list, float]

Mass density or list, if list length shoud same as ele_tags.

add_mass_from_solid(ele_tags, rho)

Add mass from tetrahedral or hexahedral elements.

Parameters

ele_tags: Union[list, int]

Element tag or list.

rho: Union[list, float]

Mass density or list, if list length shoud same as ele_tags.

get_total_mass()

Get the total mass of the model.

Returns

total_mass: float

property total_mass

Returns:

total_mass: float

The total mass.

property nodal_mass

Returns:

nodal_mass: dict[int, float]

The nodal mass dict, the key is nodeTag, value is nodal mass.

generate_ops_node_mass()

Call the OpenSeesPy node mass command to generate all node masses. The inertia moment of the rotational dof will be ignored.

Note

This function will use the mass command to generate a lumped mass matrix, and does not apply it repeatedly with the mass parameters when the element is defined. This means that if you use this function, please ignore the mass parameter in the element definition, such as the '-mass' option of some beam--column elements, and the density parameter in nDMaterial.

Returns

None

generate_ops_gravity_load(direction, factor=-9.81, exclude_nodes=None)

Call the OpenSeesPy load command to generate a nodal gravity load.

Parameters

direction: str,

The gravity load direction.

factor: float, default=-9.81

The factor applied to the mass values, it should be the multiplication of gravitational acceleration and directional indicators, e.g., -9.81, where 9.81 is the gravitational acceleration and -1 indicates along the negative Z axis. Of course, it can be multiplied by an additional factor to account for additional constant loads, e.g., 1.05 * (-9.81).

exclude_nodes: list, default=None

Excluded node tags, whose masses will not be used to generate gravity loads.

Returns

None

get_node_mass(node_tags=None)

Get nodal mass.

Parameters

node_tags: list, optional, default=None

If None, return all node masses, else return node mass in node_tags.

Returns

node_mass: dict

A dict obj whose keys are node tags and whose values are masses.

Gmsh to OpenSeesPy

class opstool.pre.Gmsh2OPS(ndm=3, ndf=3)

Generate OpenSees code from GMSH.

Parameters

ndm: int, default=3

Model dimension

ndf: int, default=3

Number of degrees of freedom.

set_output_file(filename='src.tcl', encoding='utf-8')

Parameters:

filename: str, default = “src.tcl”.

The output file-path-name must end with .tcl or .py.

encoding: str, default = “utf-8”.

The file encoding.

read_gmsh_file(file_path, encoding='utf-8', print_info=True)

Read an .msh file generated by GMSH.

Note

You only need to use one of read_gmsh_file and read_gmsh_data. read_gmsh_file is used to read data from the .msh file, and read_gmsh_data is used to read data from the runtime memory.

Parameters

file_path: str

the file path.

encoding: str, default=’utf-8’

The file encoding.

print_info: bool, default=True

Print info.

read_gmsh_data(print_info=True)

Read data from GMSH at runtime.

Note

• When using a command such as gmsh.finalize() to close gmsh, you need to use it after this command, otherwise the data cannot be read.

• You only need to use one of read_gmsh_file and read_gmsh_data. read_gmsh_file is used to read data from the .msh file, and read_gmsh_data is used to read data from the runtime memory.

Parameters

print_info: bool, default=True

Print info.

get_node_tags(dim_entity_tags=None, physical_group_names=None)

Return node tags in Gmsh, which will also be the same as in OpenSeesPy.

Return type:

list

Parameters

dim_entity_tags: list, the GMSH [(dim, entity tag), …].

A list of GMSH dimension and entity tags. If None, physical_group_names will be used.

physical_group_names: list, tuple, str, or None, default None.

The physical group name or list of physical group names. If None, dim_entity_tags will be used.

Note

• If dim_entity_tags and physical_group_names are both None, all entities will be converted.

• If dim_entity_tags and physical_group_names are both not None, dim_entity_tags will be used.

Returns

node_tags: list

A list containing node tags.

create_node_cmds(dim_entity_tags=None, physical_group_names=None)

Create OpenSeesPy nodes at runtime.

Return type:

list

Parameters

dim_entity_tags: list, the GMSH [(dim, entity tag), …].

A list of GMSH dimension and entity tags. If None, physical_group_names will be used.

physical_group_names: list, tuple, str, or None, default None.

The physical group name or list of physical group names. If None, dim_entity_tags will be used.

Note

• If dim_entity_tags and physical_group_names are both None, all entities will be converted.

• If dim_entity_tags and physical_group_names are both not None, dim_entity_tags will be used.

Returns

node_tags: list, a list containing openseespy node tags.

write_node_file(dim_entity_tags=None, physical_group_names=None)

Write a node commands file, Tcl or Python.

Parameters

dim_entity_tags: list, the GMSH [(dim, entity tag), …].

A list of GMSH dimension and entity tags. If None, physical_group_names will be used.

physical_group_names: list, tuple, str, or None, default None.

The physical group name or list of physical group names. If None, dim_entity_tags will be used.

Note

• If dim_entity_tags and physical_group_names are both None, all entities will be converted.

• If dim_entity_tags and physical_group_names are both not None, dim_entity_tags will be used.

get_element_tags(dim_entity_tags=None, physical_group_names=None)

Return element tags in Gmsh, which will also be the same as in OpenSeesPy.

Return type:

list

Parameters

dim_entity_tags: list, the GMSH [(dim, entity tag), …].

A list of dimension and entity tag containing element information that will be converted to OpenSeesPy elements. If None, physical_group_names will be used.

physical_group_names: list, tuple, str, or None, default None.

The physical group name or list of physical group names. If None, dim_entity_tags will be used.

Note

• If dim_entity_tags and physical_group_names are both None, all entities will be converted.

• If dim_entity_tags and physical_group_names are both not None, dim_entity_tags will be used.

Returns

ele_tags: list

A list containing element tags.

create_element_cmds(ops_ele_type, ops_ele_args, dim_entity_tags=None, physical_group_names=None)

Create OpenSeesPy elements at runtime.

Return type:

list

Parameters

ops_ele_type: str

the OpenSeesPy element type to generate.

ops_ele_args: list

Parameters except OpenSeesPy element tag and coordinate points.

dim_entity_tags: list, the GMSH [(dim, entity tag), …].

A list of dimension and entity tag containing element information that will be converted to OpenSeesPy elements. If None, physical_group_names will be used.

physical_group_names: list, tuple, str, or None, default None.

The physical group name or list of physical group names. If None, dim_entity_tags will be used.

Note

• If dim_entity_tags and physical_group_names are both None, all entities will be converted.

• If dim_entity_tags and physical_group_names are both not None, dim_entity_tags will be used.

Returns

ele_tags: list, a list containing openseespy element tags.

write_element_file(ops_ele_type, ops_ele_args, dim_entity_tags=None, physical_group_names=None)

Write elements a command file, Tcl or Python.

Parameters

ops_ele_type: str

the OpenSeesPy element type to generate.

ops_ele_args: list

Parameters except OpenSeesPy element tag and coordinate points.

dim_entity_tags: list, the GMSH [(dim, entity tag), …].

A list of dimension and entity tag containing element information that will be converted to OpenSeesPy elements. If None, physical_group_names will be used.

physical_group_names: list, tuple, str, or None, default None.

The physical group name or list of physical group names. If None, dim_entity_tags will be used.

Note

• If dim_entity_tags and physical_group_names are both None, all entities will be converted.

• If dim_entity_tags and physical_group_names are both not None, dim_entity_tags will be used.

Returns

ele_tags: list, a list containing openseespy element tags.

create_fix_cmds(dofs, dim_entity_tags=None, physical_group_names=None)

Create fix constraints for OpenSeesPy at runtime.

Return type:

list

Parameters

dofs: list, degrees of freedom to be constrained.

Forexample, [1, 1, 1] for 3D and 3Dof.

dim_entity_tags: list, the GMSH [(dim, entity tag), …].

A list of GMSH dimension and entity tags. If None, physical_group_names will be used.

physical_group_names: list, tuple, str, or None, default None.

The physical group name or list of physical group names. If None, dim_entity_tags will be used.

Note

• If dim_entity_tags and physical_group_names are both None, all entities will be converted.

• If dim_entity_tags and physical_group_names are both not None, dim_entity_tags will be used.

Returns

node_tags: list, a list containing openseespy fixed node tags.

write_fix_file(dofs, dim_entity_tags=None, physical_group_names=None)

Write node fix commands file, Tcl or Python.

Parameters

dofs: list, degrees of freedom to be constrained.

Forexample, [1, 1, 1] for 3D and 3Dof.

dim_entity_tags: list, the GMSH [(dim, entity tag), …].

A list of GMSH dimension and entity tags. If None, physical_group_names will be used.

physical_group_names: list, tuple, str, or None, default None.

The physical group name or list of physical group names. If None, dim_entity_tags will be used.

Note

• If dim_entity_tags and physical_group_names are both None, all entities will be converted.

• If dim_entity_tags and physical_group_names are both not None, dim_entity_tags will be used.

get_dim_entity_tags(dim=None)

Get dim_entity_tags from GMSH.

Return type:

list

Parameters

dim: int, optional, default None

The dimension tag. If None, all entities will be returned.

Returns

dim_entity_tags: list, the GMSH [(dim, entity tag), …].

get_physical_groups()

Get the GMSH physical groups.

Return type:

dict

Returns

gmsh_physical_groups: dict, the GMSH physical groups. dict[key=name, value=[(dim, entity_tag), …]]

get_boundary_dim_tags(dim_entity_tags=None, physical_group_names=None, include_self=False)

Get all boundaries of the GMSH entities, including corner points.

Return type:

list

Parameters

dim_entity_tags: list, the GMSH [(dim, entity tag), …].

A list of GMSH dimension and entity tags. If None, physical_group_names will be used.

physical_group_names: list, tuple, str, or None, default None.

The physical group name or list of physical group names. If None, dim_entity_tags will be used.

include_self: bool, default False

If True, the output contains itself, which is dim_entity_tags.

Note

• If dim_entity_tags and physical_group_names are both None, all entities will be converted.

• If dim_entity_tags and physical_group_names are both not None, dim_entity_tags will be used.

Returns

Boundary dimension and entity tags list.

Unit System

class opstool.pre.UnitSystem(length='m', force='kN', time='sec')

A class for unit conversion.

Parameters

length: str, default=”m”

Length unit base. Optional [“inch”, “ft”, “mm”, “cm”, “m”].

force: str, default=”kN”

Force unit base. Optional [“lb”(“lbf”), “kip”, “n”, “kn”, “mn”, “kgf”, “tonf”].

time: str, default=”sec”

Time unit base. Optional [“sec”, “msec”].

Note

• Mass and stress units can be automatically determined based on length and force units, optional mass units include [“mg”, “g”, “kg”, “ton”(“t”), “slug”], and optional stress units include [“pa”, “kpa”, “mpa”, “gpa”, “bar”, “psi”, “ksi”, “psf”, “ksf”].

• You can enter any uppercase and lowercase forms, such as kn and kN, mpa and MPa are equivalent.

• You can add a number after the unit to indicate a power, such as m3 for m*m*m.