Skip to content

export_tcl

export_tcl

Classes

GhostNodeElement 

GhostNodeElement(ndof: int = 3, **kwargs)

Bases: Element

Virtual element that owns mesh nodes without creating OpenSees elements.

GhostNodeElement keeps nodes in the Femora mesh and Tcl export pipeline without emitting a structural element command. It is commonly used for center-of-mass nodes, control or reference nodes, and mass application points that should not participate in element stiffness.

Note
  • Each instance receives a unique sentinel ndf value so mesh merging does not combine ghost nodes with structural nodes or with one another. At export, the sentinel is mapped back to the real DOF count through resolve_ndf.
  • to_tcl returns a Tcl comment rather than an OpenSees element command; the owning nodes are still written by the export loop.
Example 
from femora.core.model import Model

model = Model()
ghost = model.element.special.ghost_node(ndof=6)
print(ghost.real_ndof)

Create a GhostNodeElement with merge-protected sentinel DOF metadata.

Parameters:

Name Type Description Default
ndof int

Real number of DOFs per node written during Tcl export. Must be 3 or 6.

 3
**kwargs

Additional keyword arguments forwarded to the base element constructor.

 {}

Raises:

Type Description
ValueError

If ndof is not 3 or 6.
Attributes
real_ndof property 
real_ndof: int

Return the real DOF count written to the Tcl node command.

Methods:
resolve_ndf classmethod 
resolve_ndf(ndf_value: int) -> int

Map a mesh ndf value to the real DOF count for Tcl export.

If ndf_value is a ghost sentinel, it is resolved through the internal map. Otherwise the input is returned unchanged.

Parameters:

Name Type Description Default
ndf_value int

Raw ndf value from mesh point_data["ndf"].

 required

Returns:

Type Description
int

The real DOF count to write into the Tcl node command.
is_ghost_ndf classmethod 
is_ghost_ndf(ndf_value: int) -> bool

Check whether an ndf value is a ghost-node sentinel.

Parameters:

Name Type Description Default
ndf_value int

The ndf value to inspect.

 required

Returns:

Type Description
bool

True if the value is a ghost-node sentinel.
to_tcl 
to_tcl(tag: int, nodes: List[int]) -> str

Return a Tcl comment instead of an OpenSees element command.

The owning node(s) are still written by the export loop; only the element line is replaced with a comment.

Parameters:

Name Type Description Default
tag int

Element tag assigned by the manager.

 required
nodes List[int]

Node tags owned by this ghost element.

 required

Returns:

Name Type Description
str str

Tcl comment describing the ghost element.

FemoraEvent

Bases: Enum

Lifecycle signals emitted by Femora runtime subsystems.

These enum values describe when a callback is being invoked. They are not ordinary modeling commands. Instead, they mark important stages in the runtime lifecycle so advanced components can react at the right time.

The most important practical events are:

  • PRE_ASSEMBLE: emitted before the final assembled mesh is built
  • POST_ASSEMBLE: emitted after the final assembled mesh exists
  • RESOLVE_CORE_CONFLICTS: emitted after assembly when partition/core ownership updates may need follow-up work
  • PRE_EXPORT and POST_EXPORT: emitted around export-time workflows

More specialized events such as EMBEDDED_BEAM_SOLID_TCL are used by advanced exporters and interface-specific integrations.

Progress

Manages a global progress bar for reporting operation progress.

This singleton class provides a consistent way to display progress using tqdm across different parts of the Femora package. It ensures only one progress bar is active at a time and provides methods for updating and closing it.

Attributes:

Name Type Description
_bar Optional[tqdm]

The internal tqdm progress bar instance, or None if the bar has not been initialized or has been closed.
_last_value int

The last integer progress value reported (0-100).

Example:rn python`r`n from femora.utils.progress import Progress`r`n`r`n Progress.callback(value=0, desc="Loading Data")`r`n Progress.callback(value=50, message="Processing chunk 1")`r`n Progress.callback(value=100)`r`n 100%|██████████| 100/100 [...]

Methods:
callback classmethod 
callback(value: float, message: str = '', *, desc: str = 'Processing') -> None

Updates the progress bar with the given value and message.

This method ensures the progress bar is initialized (if not already) and updates its current value and postfix message. If the value reaches 100, the bar is automatically closed.

Parameters:

Name Type Description Default
value float

The current progress, a float between 0 and 100. It will be cast to an integer for display.

 required
message str

An optional short status string to display next to the bar. Defaults to an empty string.

 ''
desc str

The description for the progress bar. This is only used when the bar is created for the first time. Defaults to "Processing".

 'Processing'

Example:rn python`r`n from femora.utils.progress import Progress`r`n`r`n Progress.callback(value=0, desc="File Transfer")`r`n Progress.callback(value=25, message="Downloading part A")`r`n Progress.callback(value=75, message="Verifying checksum")`r`n Progress.callback(value=100, message="Complete")`r`n 100%|██████████| 100/100 [...] Complete

close classmethod 
close() -> None

Closes the internal tqdm progress bar and resets its state.

This method should be called explicitly if a progress operation is aborted or finishes without value reaching 100 (which automatically closes the bar). It ensures that no lingering tqdm bar remains open.

Example:rn python`r`n from femora.utils.progress import Progress`r`n`r`n Progress.callback(value=0, desc="Long Operation")`r`n Progress.close()`r`n

Functions:

_progress_callback 

_progress_callback(value: float, message: str)

Default progress reporter that uses the shared Progress utility.

_get_tcl_helper_functions 

_get_tcl_helper_functions()

Return TCL helper functions as a string.

This method contains all the TCL helper functions needed for the exported model. Embedding them directly in the code ensures they're always available and makes the package more professional and self-contained.

Returns:

Name Type Description
str

TCL helper functions

_get_tcl_file_header 

_get_tcl_file_header(required_np: int) -> str

export_to_tcl 

export_to_tcl(model, filename=None, progress_callback=None, decimals=5)

Export the model to a TCL file

Parameters:

Name Type Description Default
model

Femora Model instance with an assembled mesh.

 required
filename str

The filename to export to. If None, uses model_name in model_path

 None
progress_callback callable

Callback function to report progress. If None, uses tqdm progress bar.

 None

Returns:

Name Type Description
bool

True if export was successful, False otherwise

Raises:

Type Description
ValueError

If no filename is provided and model_name/model_path are not set