### ===================================================================================================================
### Functionality for the material properties in the vibration simulation
### ===================================================================================================================
# Copyright ©2026 Haskoning Nederland B.V.
### ===================================================================================================================
### 1. Import modules
### ===================================================================================================================
# General imports
from pathlib import Path
from typing import Optional, Union, Dict, List
# References for functions and classes in the haskoning_atr_tools package
from haskoning_atr_tools.vibration_contour_plot.helper_functions import load_data_from_file
from haskoning_atr_tools.vibration_contour_plot.simulation.material import Material
### ===================================================================================================================
### 2. Function to create Material instances from file
### ===================================================================================================================
[docs]
def create_materials_from_file(
project, file_path: Union[Path, str], sheet_name: Optional[Union[str, int]] = 0,
material: Optional[Union[str, List[str]]] = None, column_mapping: Optional[dict[str, str]] = None) \
-> Dict[str, Material]:
"""
Function to collect the material properties from file for the vibration assessment.
Input:
- project (obj): Project object containing collections of objects and project variables.
- file_path (Path or str): Path to file containing the material properties for the vibration analysis. The file
can be provided as Excel-file or csv-file. In case of Excel, the sheet name should be provided for the
worksheet with the material properties. In both cases the header should be provided in row 1.
- sheet_name (str or int): Sheet name or index of sheet with the material properties. Default value is 0,
selecting the first sheet in the Excel file. Input is ignored for csv-files.
- material (str): Select to load only the requested material or materials (when list is provided). Only
materials with this name or these names are loaded.
- column_mapping (dict): Optional input to specify other column headers for the input of the file. This might be
convenient if the data is provided with other column names. Default value is None, the default names are used
for loading the material properties from the file.
Output:
- The material properties are collected from file.
- Returns dictionary of materials.
"""
# Read file and handle the user options
df, column_mapping, _ = load_data_from_file(
file_path=file_path, sheet_name=sheet_name, column_mapping=column_mapping,
default_column_mapping={
'name': 'Name',
'density': 'Density [kg/m3]',
'shear_modulus': 'Shear modulus [GPa]',
'poisson_ratio': 'Poisson’s ratio',
'quality_factor': 'Quality factor'})
# Check filter
if isinstance(material, str):
material = [material]
# Loop through rows with material data
materials_from_file = {}
for i, row in df.iterrows():
# Check the ID as unique identifier for the equipment
material_name = row[column_mapping['name']]
if material and material_name not in material:
continue
if material_name in materials_from_file:
raise ValueError(f"ERROR: Please provide unique name for the material. Duplicate name: {material_name}.")
# Create the instance of the equipment, validation executed in class
material_object = Material(
name=material_name, density=row[column_mapping['density']],
shear_modulus=row[column_mapping['shear_modulus']], poisson_ratio=row[column_mapping['poisson_ratio']],
quality_factor=row[column_mapping['quality_factor']])
material_object.project = project
materials_from_file[material_name] = material_object
return materials_from_file
### ===================================================================================================================
### 3. End of script
### ===================================================================================================================