Skip to content

Concepts Overview

Femora is a Python modeling layer for building OpenSees models from reusable, inspectable parts. The important idea is that you do not write one long solver script first. You describe a model in Python, inspect it while it is still organized, assemble it into a global mesh, and then export or run the solver workflow.

The Big Idea

Large finite element models are hard to maintain when geometry, material definitions, boundary conditions, loading, analysis settings, and output commands are mixed together. Femora separates those responsibilities into a sequence:

flowchart LR
    model(("Model"))
    managers["Managers<br/>organized namespaces"]
    components["Building blocks<br/>materials, sections, elements"]
    mesh["Mesh parts<br/>independent geometry"]
    interfaces["Interfaces<br/>relationships between mesh parts"]
    assembly{{"Assembly<br/>global mesh, tags, partitions"}}
    behavior["Model behavior<br/>constraints, loads, damping,<br/>recorders, analyses"]
    process["Process<br/>ordered execution steps"]
    results(("Export and results<br/>Tcl, VTK, JSON, solver output"))

    model --> managers
    managers --> components
    components --> mesh
    mesh --> interfaces
    interfaces --> assembly
    assembly --> behavior
    behavior --> process
    process --> results

    classDef root stroke-width:2px;
    classDef stage stroke-width:1px;
    classDef compile stroke-width:2px;

    class model,results root;
    class managers,components,mesh,interfaces,behavior,process stage;
    class assembly compile;

The Concepts section follows this same order. Each page explains one stage, then points to the next stage in the modeling chain.

Femora is not just a Tcl writer

Femora keeps a model in memory before export. That means you can inspect mesh parts, plot intermediate geometry, debug interfaces, attach metadata, and organize outputs before committing to a solver run.

Before And After Assembly

Femora is easiest to understand if you divide the workflow into three phases:

Phase What you do Why it matters
Before assembly Create the model, managers, building blocks, mesh parts, and interfaces. You are defining reusable ingredients and local geometry sources.
Assembly Compile mesh parts and interfaces into one global assembled model. Femora creates final topology, tags, partitions, and source metadata.
After assembly Add behavior, selections, recorders, analyses, process steps, and exports. These objects usually refer to the assembled model or solver workflow.

This split is important because some objects must exist before assembly, while others only make full sense after the global mesh exists. Building blocks, mesh parts, and interfaces prepare the model. Assembly resolves the global model. Constraints, groups, damping, recorders, analyses, and process steps describe what happens to that assembled model.

Why This Matters

  • Scriptable

    Build repeatable models with Python objects instead of manually maintaining one long solver script.

  • Inspectable

    Plot mesh parts, interfaces, and the assembled model while developing instead of waiting until after a solver run.

  • Composable

    Combine soil blocks, structural members, boundaries, and loading workflows as separate pieces.

  • Selectable

    Target parts of the model by source, region, or group when assigning damping, recorders, and outputs.

  • Assembly-Aware

    Let the assembler create final connectivity, solver tags, source metadata, and interface updates.

  • Partition-Aware

    Prepare assembled meshes for large parallel OpenSees workflows by assigning cells to computational cores.

A Femora Model In One Screen

This is the workflow shape, not a full tutorial:

from femora.core.model import Model

model = Model()

# 1. Define reusable building blocks.
#    Examples: materials, sections, element templates, time series.

# 2. Use building blocks to create mesh parts.
#    Mesh parts are independent geometry sources.

# 3. Declare interfaces between mesh parts when needed.
#    Interfaces are declared before assembly because they modify the assembled model.

# 4. Assemble.
#    This creates the global mesh, final tags, partitions, and source metadata.

# 5. Add model behavior and process steps.
#    Examples: constraints, loads, damping, recorders, analyses, actions.

# 6. Export or run the workflow.
#    Examples: Tcl, VTK, JSON, solver output files.

The later concept pages replace these comments with concrete API examples.

Three Things To Remember

1. The model is the workspace

Model() is the root object for one modeling workspace. It owns the manager namespaces, assembled mesh state, process steps, and export state.

2. Building blocks are reusable definitions

Materials, sections, transformations, and element templates are pre-assembly building blocks. They can be created once and reused by later mesh parts.

3. Assembly is the compile step

Mesh parts are source geometry before assembly. The assembler combines them into the final global mesh and resolves node tags, element tags, partitions, source metadata, and interface updates.

Plot early

A strong Femora workflow is visual and incremental: plot individual mesh parts first, assemble, then plot the assembled model with metadata such as Core, ElementTag, FemoraPartTag, or other exported cell data.

What This Section Teaches

  • Model

    Understand the root workspace that keeps one Femora model organized.

  • Managers

    Learn how model-owned namespaces split creation, tracking, and coordination responsibilities.

  • Building Blocks

    Learn how materials, sections, transformations, and element templates are prepared before mesh parts.

  • Mesh Parts

    Define independent geometric sources that use building blocks.

  • Interfaces

    Understand assembly-time relationships between independent mesh parts.

  • Assembly

    Compile independent geometry and interfaces into one assembled model.

  • Partitioning

    Divide assembly sections into subdomains while retaining control over computational ownership.

  • The Assembled Model

    Understand the final pyvista.UnstructuredGrid and the point and cell data carried into later operations.

  • Tags and IDs

    Learn how Femora identifies managed definitions, mesh data, and exported solver objects.

  • Regions and Groups

    Apply physical scope before assembly and create reusable selections afterward.

  • Damping

    Define an energy-dissipation law and assign it to the intended model region.

  • Constraints

    Restrain nodal motion and define kinematic relationships between assembled nodes.

  • Loading

    Connect model targets, reference values, time histories, and loading patterns.

  • Recorders and Actions

    Observe runtime response and define deliberate transitions between simulation stages.

  • Analysis

    Choose a coherent numerical strategy for advancing load or time.

  • Process

    Arrange patterns, recorders, actions, and analyses into the final executable timeline.

Common Confusions

Mesh parts are not the final mesh

Global OpenSees node and element tags are finalized during assembly, not when a mesh part is created.

Interfaces are declared before assembly

Interfaces reference mesh parts first, then perform detailed search or mapping work during assembly events.

Analysis is separate from geometry

The physical model and the solver process are separate. Build the model first, then define how it will be analyzed.