TimeSeries

Understanding the TimeSeriesManager

The TimeSeriesManager is a core component of the Femora library that serves as a centralized system for creating, retrieving, tracking, and managing time series objects. It implements the Singleton pattern to ensure a single, consistent point of time series management across the entire application.

Time series defined in Femora are automatically tracked, tagged, and organized by the TimeSeriesManager, simplifying the process of creating dynamic models with time-varying loads, displacements, or boundary conditions.

Accessing the TimeSeriesManager

There are two ways to access the TimeSeriesManager in your code:

Direct Access: Import and use the TimeSeriesManager class directly

from femora.components.TimeSeries.timeSeriesBase import TimeSeriesManager

# Get the singleton instance
timeseries_manager = TimeSeriesManager()

# Use the time series manager directly
timeseries_manager.create_time_series(...)

Through Femora (Recommended): Access via the Femora class’s .timeSeries property

import femora as fm

# Create a Femora instance

# Access the TimeSeriesManager through the .timeSeries property
fm.timeSeries.create_time_series(...)

The second approach is recommended as it provides a unified interface to all of Femora’s components and ensures proper initialization of all dependencies.

How TimeSeriesManager Works

The TimeSeriesManager provides several key capabilities:

Time Series Creation: Creates time series objects of various types with appropriate parameters
Time Series Tracking: Keeps track of all time series by tag and name
Time Series Tagging: Automatically assigns sequential tags to time series
Time Series Management: Provides methods to retrieve, update, and delete time series

When a time series is created, the TimeSeriesManager:

Assigns a unique numeric tag automatically
Registers it with the user-provided name (if provided)
Validates that all required parameters are present and valid

TimeSeriesManager API Reference

class femora.components.TimeSeries.timeSeriesBase.TimeSeriesManager[source]

Bases: object

Singleton class for managing time series objects in the application.

This manager provides a centralized way to create, retrieve, and manage time series objects. It maintains a singleton instance to ensure consistent access to time series throughout the application.

clear_all()[source]

Clears all time series from the registry.

This method clears all registered time series objects, effectively resetting the state of the time series management system.

Example

manager = TimeSeriesManager() # Create some time series # … # Clear all time series when starting a new model manager.clear_all()

create_time_series(series_type, **kwargs)[source]

Create a new time series of the specified type.

This method delegates to the TimeSeriesRegistry to create a new time series object with the provided parameters.

Parameters:

series_type (str) – The type of time series to create (e.g., ‘constant’, ‘linear’)
**kwargs – Parameters specific to the time series type initialization

Returns:

A new time series instance

Return type:

TimeSeries

Raises:

KeyError – If the requested time series type is not registered
ValueError – If validation of parameters fails

get_all_time_series()[source]

Retrieve all registered time series objects.

Returns:: A dictionary of all time series objects, where keys are the tags and values are the TimeSeries objects
Return type:: Dict[int, TimeSeries]

get_available_types()[source]

Get a list of all available time series types that can be created.

Returns:: A list of strings representing available time series types
Return type:: List[str]

Example

manager = TimeSeriesManager() types = manager.get_available_types() print(“Available time series types:”, types)

get_time_series(tag)[source]

Retrieve a specific time series by its tag.

Parameters:: tag (int) – The unique identifier tag of the time series
Returns:: The time series object with the specified tag
Return type:: TimeSeries
Raises:: KeyError – If no time series with the given tag exists

remove_time_series(tag)[source]

Remove a time series by its tag.

This method removes the time series with the given tag and reassigns sequential tags to all remaining time series objects.

Parameters:: tag (int) – The tag of the time series to remove
Return type:: None

class TimeSeriesManager

Singleton class for managing time series objects in the application.

clear_all(self)

No-index:

Clears all time series from the registry.

create_time_series(self, series_type: str, **kwargs) → TimeSeries

No-index:

Create a new time series of the specified type.

Parameters:

series_type (str) – The type of time series to create
kwargs – Parameters specific to the time series type initialization

Returns:

A new time series instance

Return type:

TimeSeries

get_time_series(self, tag: int) → TimeSeries

No-index:

Retrieve a specific time series by its tag.

Parameters:: tag (int) – The unique identifier tag of the time series
Returns:: The time series object with the specified tag
Return type:: TimeSeries

get_all_time_series(self) → Dict[int, TimeSeries]

No-index:

Retrieve all registered time series objects.

Returns:: A dictionary of all time series objects
Return type:: Dict[int, TimeSeries]

get_available_types(self) → List[str]

No-index:

Get a list of all available time series types.

Returns:: A list of available time series types
Return type:: List[str]

remove_time_series(self, tag: int) → None

No-index:

Remove a time series by its tag.

Parameters:: tag (int) – The tag of the time series to remove

Time Series Creation

Creating time series is one of the primary functions of the TimeSeriesManager. When creating a time series, you need to specify:

series_type: Specifies the type of time series. Available types include: - Constant: A constant value across all time - Linear: Linear interpolation between specified time-value pairs - Path: Load time series from a path - Path Time: Load time and value series from separate paths - Trig: Trigonometric function (sine, cosine) - PulseTrain: Series of pulse loadings
Time series-specific parameters: Each time series type requires specific parameters

The TimeSeriesManager handles all the details of creating the appropriate time series object based on these parameters, ensuring type safety and parameter validation.

Usage Example

import femora as fm

# Create a femora instance


# Create a constant time series
constant_ts = fm.timeSeries.create_time_series(
    'Constant',
    factor=1.0
)

# Create a linear time series
linear_ts = fm.timeSeries.create_time_series(
    'Linear',
    time_points=[0.0, 0.1, 0.2, 0.5, 1.0],
    factor_points=[0.0, 0.2, 0.5, 0.8, 1.0]
)

# Create a path time series from a file
path_ts = fm.timeSeries.create_time_series(
    'Path',
    file_path='data/acceleration.txt',
    dt=0.01,
    factor=9.81
)

# Create a trigonometric time series
trig_ts = fm.timeSeries.create_time_series(
    'Trig',
    trig_type='Sine',  # 'Sine' or 'Cosine'
    period=1.0,
    phase_shift=0.0,
    factor=1.0
)

Available Time Series Types

The time series types available in Femora provide various ways to define time-dependent behavior. Follow the links above to explore the different time series types available.

Each time series type has its own documentation page with detailed parameter descriptions and usage examples.

Applying Time Series

Time series can be applied to various aspects of your model:

Pattern Application: Used with UniformExcitation or other patterns
Load Application: Applied to nodal loads, surface loads, etc.
Boundary Condition Application: For time-varying boundary conditions

Example of applying a time series to a uniform excitation pattern:

# Create a time series for ground motion
ground_motion_ts = fm.timeSeries.create_time_series(
    'Path',
    file_path='ground_motion.txt',
    dt=0.01,
    factor=1.0
)

# Create a pattern using the time series
fm.pattern.create_pattern(
    'uniformexcitation',
    dof=1,  # X direction
    time_series=ground_motion_ts,
    vel0=0.0
)