Atomizer/docs/generated/EXTRACTORS.md

Atomizer Extractor Library

Auto-generated: 2025-12-07 12:53

This document is automatically generated from the extractor source code.

---

Quick Reference

Extractor	Category	Phase	Description
check_force_equilibrium	forces	Phase 2	Check if reaction forces balance applied loads (equilibrium
extract_reaction_component	forces	Phase 2	Extract maximum absolute value of a specific reaction compon
extract_spc_forces	forces	Phase 2	Extract SPC (reaction) forces from boundary conditions.
extract_total_reaction_force	forces	Phase 2	Convenience function to extract total reaction force magnitu
extract_frequencies	general	Phase 3	Extract natural frequencies from modal analysis F06 file.
extract_part_material	general	Phase 1	Convenience function to extract just material info.
PartMassExtractor	mass	Phase 1	Class-based extractor for part mass and material with cachin
extract_part_mass	mass	Phase 1	Convenience function to extract just the mass in kg.
extract_part_mass_material	mass	Phase 1	Extract mass and material properties from NX part file.
extract_modal_mass	modal	Phase 3	Extract modal effective mass from F06 file.
get_first_frequency	modal	Phase 3	Get first natural frequency from F06 file.
get_modal_mass_ratio	modal	Phase 3	Get cumulative modal mass ratio for first n modes.
ZernikeExtractor	optical	Phase 1	Complete Zernike analysis extractor for telescope mirror opt
extract_zernike_filtered_rms	optical	Phase 1	Extract filtered RMS WFE - the primary metric for mirror opt
extract_zernike_from_op2	optical	Phase 1	Convenience function to extract Zernike metrics from OP2.
extract_zernike_relative_rms	optical	Phase 1	Extract relative filtered RMS between two subcases.
extract_strain_energy	strain	Phase 2	Extract strain energy from structural elements.
extract_strain_energy_density	strain	Phase 2	Extract strain energy density (energy per volume).
extract_total_strain_energy	strain	Phase 2	Convenience function to extract total strain energy.
extract_max_principal_stress	stress	Phase 2	Convenience function to extract maximum principal stress.
extract_min_principal_stress	stress	Phase 2	Convenience function to extract minimum principal stress.
extract_principal_stress	stress	Phase 2	Extract principal stresses from solid or shell elements.
extract_solid_stress	stress	Phase 1	Extract stress from solid elements.
extract_heat_flux	thermal	Phase 3	Extract element heat flux from thermal analysis OP2 file.
extract_temperature	thermal	Phase 3	Extract nodal temperatures from thermal analysis OP2 file.
extract_temperature_gradient	thermal	Phase 3	Extract temperature gradients from thermal analysis.
get_max_temperature	thermal	Phase 3	Get maximum temperature from OP2 file.

---

Forces Extractors

check_force_equilibrium

Module: optimization_engine.extractors.extract_spc_forces Phase: Phase 2

Parameters:

• op2_file
• applied_load = None
• tolerance = 1.0

Description:

Check if reaction forces balance applied loads (equilibrium check).

In a valid static analysis, sum of reactions should equal applied loads.

Args:
    op2_file: Path to .op2 file
    applied_load: Optional dict of applied loads {'fx': N, 'fy': N, 'fz': N}
    tolerance: Tolerance for equilibrium check (default 1.0 N)

Returns:
    dict: {
        'in_equilibrium': Boolean,
        'reaction_sum': [fx, fy, fz],
        'imbalance': [dx, dy, dz] (if applied_load provided),
        'max_imbalance': Maximum component imbalance
    }

---

extract_reaction_component

Module: optimization_engine.extractors.extract_spc_forces Phase: Phase 2

Parameters:

• op2_file
• component = fz
• subcase = 1

Description:

Extract maximum absolute value of a specific reaction component.

Args:
    op2_file: Path to .op2 file
    component: 'fx', 'fy', 'fz', 'mx', 'my', 'mz'
    subcase: Subcase ID

Returns:
    Maximum absolute value of the specified component

---

extract_spc_forces

Module: optimization_engine.extractors.extract_spc_forces Phase: Phase 2

Parameters:

• op2_file
• subcase = 1
• component = total

Description:

Extract SPC (reaction) forces from boundary conditions.

SPC forces are the reaction forces at constrained nodes. They balance
the applied loads and indicate load path through the structure.

Args:
    op2_file: Path to .op2 file
    subcase: Subcase ID (default 1)
    component: Which component(s) to return:
        - 'total': Resultant force magnitude (sqrt(fx^2+fy^2+fz^2))
        - 'fx', 'fy', 'fz': Individual force components
        - 'mx', 'my', 'mz': Individual moment components
        - 'force': Vector sum of forces only
        - 'moment': Vector sum of moments only

Returns:
    dict: {
        'total_reaction': Total reaction force magnitude,
        'max_reaction': Maximum nodal reaction,
        'max_reaction_node': Node ID with max reaction,
        'sum_fx': Sum of Fx at all nodes,
        'sum_fy': Sum of Fy at all nodes,
        'sum_fz': Sum of Fz at all nodes,
        'sum_mx': Sum of Mx at all nodes,
        'sum_my': Sum of My at all nodes,
        'sum_mz': Sum of Mz at all nodes,
        'node_reactions': Dict of {node_id: [fx,fy,fz,mx,my,mz]},
        'num_constrained_nodes': Number of nodes with SPCs,
        'subcase': Subcase ID,
        'units': 'N, N-mm (model units)'
    }

Example:
    >>> result = extract_spc_forces('model.op2')
    >>> print(f"Total reaction: {result['total_reaction']:.2f} N")
    >>> print(f"Sum Fz: {result['sum_fz']:.2f} N")

---

extract_total_reaction_force

Module: optimization_engine.extractors.extract_spc_forces Phase: Phase 2

Parameters:

• op2_file
• subcase = 1

Description:

Convenience function to extract total reaction force magnitude.

Args:
    op2_file: Path to .op2 file
    subcase: Subcase ID

Returns:
    Total reaction force magnitude (N)

---

General Extractors

extract_frequencies

Module: optimization_engine.extractors.extract_modal_mass Phase: Phase 3

Parameters:

• f06_file
• n_modes = None

Description:

Extract natural frequencies from modal analysis F06 file.

Simpler version of extract_modal_mass that just gets frequencies.

Args:
    f06_file: Path to F06 file
    n_modes: Number of modes to extract (default: all)

Returns:
    dict: {
        'success': bool,
        'frequencies': list of frequencies in Hz,
        'mode_count': int,
        'first_frequency': float,
        'error': str or None
    }

---

extract_part_material

Module: optimization_engine.extractors.extract_part_mass_material Phase: Phase 1

Parameters:

• prt_file
• properties_file = None

Description:

Convenience function to extract just material info.

Args:
    prt_file: Path to .prt file
    properties_file: Optional explicit path to temp file

Returns:
    Dictionary with 'name', 'density', 'density_unit'

Example:
    >>> mat = extract_part_material('model.prt')
    >>> print(f"Material: {mat['name']}, Density: {mat['density']}")
    Material: Steel_304, Density: 7.93e-06

---

Mass Extractors

PartMassExtractor

Module: optimization_engine.extractors.extract_part_mass_material Phase: Phase 1

Parameters:

• prt_file
• properties_file = None

Description:

Class-based extractor for part mass and material with caching.

Use this when you need to extract properties from multiple parts
or want to cache results.

Example:
    >>> extractor = PartMassExtractor('model.prt')
    >>> result = extractor.extract()
    >>> print(result['mass_kg'])
    1.234

---

extract_part_mass

Module: optimization_engine.extractors.extract_part_mass_material Phase: Phase 1

Parameters:

• prt_file
• properties_file = None

Description:

Convenience function to extract just the mass in kg.

Args:
    prt_file: Path to .prt file
    properties_file: Optional explicit path to temp file

Returns:
    Mass in kilograms (float)

Example:
    >>> mass = extract_part_mass('model.prt')
    >>> print(f"Mass: {mass:.3f} kg")
    Mass: 1.234 kg

---

extract_part_mass_material

Module: optimization_engine.extractors.extract_part_mass_material Phase: Phase 1

Parameters:

• prt_file
• properties_file = None

Description:

Extract mass and material properties from NX part file.

This function reads from a temp JSON file that must be created by
running the NX journal: nx_journals/extract_part_mass_material.py

Args:
    prt_file: Path to .prt file (used to locate temp file)
    properties_file: Optional explicit path to _temp_part_properties.json
                    If not provided, looks in same directory as prt_file

Returns:
    Dictionary containing:
    - 'mass_kg': Mass in kilograms (float)
    - 'mass_g': Mass in grams (float)
    - 'volume_mm3': Volume in mm^3 (float)
    - 'surface_area_mm2': Surface area in mm^2 (float)
    - 'center_of_gravity_mm': [x, y, z] in mm (list)
    - 'moments_of_inertia': {'Ixx', 'Iyy', 'Izz', 'unit'} or None
    - 'material': {'name', 'density', 'density_unit'} (dict)
    - 'num_bodies': Number of solid bodies (int)

Raises:
    FileNotFoundError: If prt file or temp properties file not found
    ValueError: If temp file has invalid format or extraction failed

Example:
    >>> result = extract_part_mass_material('model.prt')
    >>> print(f"Mass: {result['mass_kg']:.3f} kg")
    Mass: 1.234 kg
    >>> print(f"Material: {result['material']['name']}")
    Material: Aluminum_6061

Note:
    Before calling this function, you must run the NX journal to
    create the temp file:
    ```
    run_journal.exe extract_part_mass_material.py model.prt
    ```

---

Modal Extractors

extract_modal_mass

Module: optimization_engine.extractors.extract_modal_mass Phase: Phase 3

Parameters:

• f06_file
• mode = None
• direction = all

Description:

Extract modal effective mass from F06 file.

Modal effective mass indicates how much of the total mass participates
in each mode for each direction. Important for:
- Base excitation problems
- Seismic analysis
- Random vibration

Args:
    f06_file: Path to the F06 results file
    mode: Mode number to extract (1-indexed). If None, returns all modes.
    direction: Direction(s) to extract:
               'x', 'y', 'z' - single direction
               'all' - all directions (default)
               'total' - sum of all directions

Returns:
    dict: {
        'success': bool,
        'modes': list of mode data (if mode=None),
        'modal_mass_x': float (kg) - effective mass in X,
        'modal_mass_y': float (kg) - effective mass in Y,
        'modal_mass_z': float (kg) - effective mass in Z,
        'modal_mass_rx': float (kg·m²) - rotational mass about X,
        'modal_mass_ry': float (kg·m²) - rotational mass about Y,
        'modal_mass_rz': float (kg·m²) - rotational mass about Z,
        'participation_x': float (0-1) - participation factor X,
        'participation_y': float (0-1) - participation factor Y,
        'participation_z': float (0-1) - participation factor Z,
        'frequency': float (Hz) - natural frequency,
        'cumulative_mass_x': float - cumulative mass fraction X,
        'cumulative_mass_y': float - cumulative mass fraction Y,
        'cumulative_mass_z': float - cumulative mass fraction Z,
        'total_mass': float (kg) - total model mass,
        'error': str or None
    }

Example:
    >>> result = extract_modal_mass("modal_analysis.f06", mode=1)
    >>> if result['success']:
    ...     print(f"Mode 1 frequency: {result['frequency']:.2f} Hz")
    ...     print(f"X participation: {result['participation_x']*100:.1f}%")

---

get_first_frequency

Module: optimization_engine.extractors.extract_modal_mass Phase: Phase 3

Parameters:

• f06_file

Description:

Get first natural frequency from F06 file.

Convenience function for optimization constraints.
Returns 0 if extraction fails.

Args:
    f06_file: Path to F06 file

Returns:
    float: First natural frequency in Hz, or 0 on failure

---

get_modal_mass_ratio

Module: optimization_engine.extractors.extract_modal_mass Phase: Phase 3

Parameters:

• f06_file
• direction = z
• n_modes = 10

Description:

Get cumulative modal mass ratio for first n modes.

This indicates what fraction of total mass participates in the
first n modes. Important for determining if enough modes are included.

Args:
    f06_file: Path to F06 file
    direction: Direction ('x', 'y', or 'z')
    n_modes: Number of modes to include

Returns:
    float: Cumulative mass ratio (0-1), or 0 on failure

---

Optical Extractors

ZernikeExtractor

Module: optimization_engine.extractors.extract_zernike Phase: Phase 1

Parameters:

• op2_path
• bdf_path = None
• displacement_unit = mm
• n_modes = 50
• filter_orders = 4

Description:

Complete Zernike analysis extractor for telescope mirror optimization.

This class handles:
- Loading OP2 displacement results
- Matching with BDF geometry
- Computing Zernike coefficients and RMS metrics
- Multi-subcase analysis (different gravity orientations)
- Relative metrics between subcases

Example usage in optimization:
    extractor = ZernikeExtractor(op2_file, bdf_file)

    # For single-objective optimization (minimize filtered RMS at 20 deg)
    result = extractor.extract_subcase('20')
    objective = result['filtered_rms_nm']

    # For multi-subcase optimization
    all_results = extractor.extract_all_subcases()

---

extract_zernike_filtered_rms

Module: optimization_engine.extractors.extract_zernike Phase: Phase 1

Parameters:

• op2_file
• bdf_file = None
• subcase = 1
• kwargs

Description:

Extract filtered RMS WFE - the primary metric for mirror optimization.

Filtered RMS removes piston, tip, tilt, and defocus (modes 1-4),
which can be corrected by alignment and focus adjustment.

Args:
    op2_file: Path to OP2 file
    bdf_file: Path to BDF geometry (auto-detected if None)
    subcase: Subcase identifier
    **kwargs: Additional arguments for ZernikeExtractor

Returns:
    Filtered RMS WFE in nanometers

---

extract_zernike_from_op2

Module: optimization_engine.extractors.extract_zernike Phase: Phase 1

Parameters:

• op2_file
• bdf_file = None
• subcase = 1
• displacement_unit = mm
• n_modes = 50
• filter_orders = 4

Description:

Convenience function to extract Zernike metrics from OP2.

This is the main entry point for optimization objectives.

Args:
    op2_file: Path to OP2 results file
    bdf_file: Path to BDF geometry (auto-detected if None)
    subcase: Subcase identifier
    displacement_unit: Unit of displacement in OP2
    n_modes: Number of Zernike modes
    filter_orders: Low-order modes to filter

Returns:
    Dict with:
    - 'global_rms_nm': Global RMS WFE in nanometers
    - 'filtered_rms_nm': Filtered RMS (low orders removed)
    - 'defocus_nm', 'astigmatism_rms_nm', etc.: Individual aberrations

---

extract_zernike_relative_rms

Module: optimization_engine.extractors.extract_zernike Phase: Phase 1

Parameters:

• op2_file
• target_subcase
• reference_subcase
• bdf_file = None
• kwargs

Description:

Extract relative filtered RMS between two subcases.

Useful for analyzing gravity-induced deformation relative to
a reference orientation (e.g., polishing position).

Args:
    op2_file: Path to OP2 file
    target_subcase: Subcase to analyze
    reference_subcase: Reference subcase
    bdf_file: Path to BDF geometry
    **kwargs: Additional arguments for ZernikeExtractor

Returns:
    Relative filtered RMS WFE in nanometers

---

Strain Extractors

extract_strain_energy

Module: optimization_engine.extractors.extract_strain_energy Phase: Phase 2

Parameters:

• op2_file
• subcase = 1
• element_type = None
• top_n = 10

Description:

Extract strain energy from structural elements.

Strain energy (U) is a measure of the work done to deform the structure:
U = 0.5 * integral(sigma * epsilon) dV

High strain energy density indicates highly stressed regions.

Args:
    op2_file: Path to .op2 file
    subcase: Subcase ID (default 1)
    element_type: Filter by element type (e.g., 'ctetra', 'chexa', 'cquad4')
                 If None, returns total from all elements
    top_n: Number of top elements to return by strain energy

Returns:
    dict: {
        'total_strain_energy': Total strain energy (all elements),
        'mean_strain_energy': Mean strain energy per element,
        'max_strain_energy': Maximum element strain energy,
        'max_energy_element': Element ID with max strain energy,
        'top_elements': List of (element_id, energy) tuples,
        'energy_by_type': Dict of {element_type: total_energy},
        'num_elements': Total element count,
        'subcase': Subcase ID,
        'units': 'N-mm (model units)'
    }

Example:
    >>> result = extract_strain_energy('model.op2')
    >>> print(f"Total strain energy: {result['total_strain_energy']:.2f} N-mm")
    >>> print(f"Highest energy element: {result['max_energy_element']}")

---

extract_strain_energy_density

Module: optimization_engine.extractors.extract_strain_energy Phase: Phase 2

Parameters:

• op2_file
• subcase = 1
• element_type = ctetra

Description:

Extract strain energy density (energy per volume).

Strain energy density is useful for identifying critical regions
and for material utilization optimization.

Args:
    op2_file: Path to .op2 file
    subcase: Subcase ID
    element_type: Element type to analyze

Returns:
    dict: {
        'max_density': Maximum strain energy density,
        'mean_density': Mean strain energy density,
        'total_energy': Total strain energy,
        'units': 'N/mm^2 (MPa equivalent)'
    }

Note:
    This requires element volume data which may not always be available.
    Falls back to energy-only metrics if volume is unavailable.

---

extract_total_strain_energy

Module: optimization_engine.extractors.extract_strain_energy Phase: Phase 2

Parameters:

• op2_file
• subcase = 1

Description:

Convenience function to extract total strain energy.

Args:
    op2_file: Path to .op2 file
    subcase: Subcase ID

Returns:
    Total strain energy (N-mm)

---

Stress Extractors

extract_max_principal_stress

Module: optimization_engine.extractors.extract_principal_stress Phase: Phase 2

Parameters:

• op2_file
• subcase = 1
• element_type = ctetra

Description:

Convenience function to extract maximum principal stress.

Args:
    op2_file: Path to .op2 file
    subcase: Subcase ID
    element_type: Element type

Returns:
    Maximum principal stress value (tension positive)

---

extract_min_principal_stress

Module: optimization_engine.extractors.extract_principal_stress Phase: Phase 2

Parameters:

• op2_file
• subcase = 1
• element_type = ctetra

Description:

Convenience function to extract minimum principal stress.

For solid elements, returns sigma3 (most compressive).
For shell elements, returns sigma2.

Args:
    op2_file: Path to .op2 file
    subcase: Subcase ID
    element_type: Element type

Returns:
    Minimum principal stress value (compression negative)

---

extract_principal_stress

Module: optimization_engine.extractors.extract_principal_stress Phase: Phase 2

Parameters:

• op2_file
• subcase = 1
• element_type = ctetra
• principal = max

Description:

Extract principal stresses from solid or shell elements.

Principal stresses are the eigenvalues of the stress tensor,
ordered as: sigma1 >= sigma2 >= sigma3 (o1 >= o2 >= o3)

Args:
    op2_file: Path to .op2 file
    subcase: Subcase ID (default 1)
    element_type: Element type ('ctetra', 'chexa', 'cquad4', 'ctria3')
    principal: Which principal stress to return:
        - 'max': Maximum principal (sigma1, tension positive)
        - 'mid': Middle principal (sigma2)
        - 'min': Minimum principal (sigma3, compression negative)
        - 'all': Return all three principals

Returns:
    dict: {
        'max_principal': Maximum principal stress value,
        'min_principal': Minimum principal stress value,
        'mid_principal': Middle principal stress (if applicable),
        'max_element': Element ID with maximum principal,
        'min_element': Element ID with minimum principal,
        'von_mises_max': Max von Mises for comparison,
        'element_type': Element type used,
        'subcase': Subcase ID,
        'units': 'MPa (model units)'
    }

Example:
    >>> result = extract_principal_stress('model.op2', element_type='ctetra')
    >>> print(f"Max tension: {result['max_principal']:.2f} MPa")
    >>> print(f"Max compression: {result['min_principal']:.2f} MPa")

---

extract_solid_stress

Module: optimization_engine.extractors.extract_von_mises_stress Phase: Phase 1

Parameters:

• op2_file
• subcase = 1
• element_type = ctetra

Description:

Extract stress from solid elements.

---

Thermal Extractors

extract_heat_flux

Module: optimization_engine.extractors.extract_temperature Phase: Phase 3

Parameters:

• op2_file
• subcase = 1
• element_type = all

Description:

Extract element heat flux from thermal analysis OP2 file.

Args:
    op2_file: Path to the OP2 results file
    subcase: Subcase number
    element_type: Element type to extract ('all', 'ctetra', 'chexa', etc.)

Returns:
    dict: {
        'success': bool,
        'max_heat_flux': float (W/mm² or model units),
        'min_heat_flux': float,
        'avg_heat_flux': float,
        'max_element_id': int,
        'element_count': int,
        'unit': str,
        'error': str or None
    }

---

extract_temperature

Module: optimization_engine.extractors.extract_temperature Phase: Phase 3

Parameters:

• op2_file
• subcase = 1
• nodes = None
• return_field = False

Description:

Extract nodal temperatures from thermal analysis OP2 file.

Args:
    op2_file: Path to the OP2 results file
    subcase: Subcase number to extract (default: 1)
    nodes: Optional list of specific node IDs to extract.
           If None, extracts all nodes.
    return_field: If True, include full temperature field in result

Returns:
    dict: {
        'success': bool,
        'max_temperature': float (K or °C depending on model units),
        'min_temperature': float,
        'avg_temperature': float,
        'max_node_id': int (node with max temperature),
        'min_node_id': int (node with min temperature),
        'node_count': int,
        'temperatures': dict (node_id: temp) - only if return_field=True,
        'unit': str ('K' or 'C'),
        'subcase': int,
        'error': str or None
    }

Example:
    >>> result = extract_temperature("thermal_analysis.op2", subcase=1)
    >>> if result['success']:
    ...     print(f"Max temp: {result['max_temperature']:.1f} K at node {result['max_node_id']}")
    ...     print(f"Temperature range: {result['min_temperature']:.1f} - {result['max_temperature']:.1f} K")

---

extract_temperature_gradient

Module: optimization_engine.extractors.extract_temperature Phase: Phase 3

Parameters:

• op2_file
• subcase = 1
• method = nodal_difference

Description:

Extract temperature gradients from thermal analysis.

Computes temperature gradients based on nodal temperature differences.
This is useful for identifying thermal stress hot spots.

Args:
    op2_file: Path to the OP2 results file
    subcase: Subcase number
    method: Gradient calculation method:
            - 'nodal_difference': Max temperature difference between adjacent nodes
            - 'element_based': Gradient within elements (requires mesh connectivity)

Returns:
    dict: {
        'success': bool,
        'max_gradient': float (K/mm or temperature units/length),
        'avg_gradient': float,
        'temperature_range': float (max - min temperature),
        'gradient_location': tuple (node_id_hot, node_id_cold),
        'error': str or None
    }

Note:
    For accurate gradients, element-based calculation requires mesh connectivity
    which may not be available in all OP2 files. The nodal_difference method
    provides an approximation based on temperature range.

---

get_max_temperature

Module: optimization_engine.extractors.extract_temperature Phase: Phase 3

Parameters:

• op2_file
• subcase = 1

Description:

Get maximum temperature from OP2 file.

Convenience function for use in optimization constraints.
Returns inf if extraction fails.

Args:
    op2_file: Path to OP2 file
    subcase: Subcase number

Returns:
    float: Maximum temperature or inf on failure

---