DOI: 10.5281/zenodo.17865072
title: MatViz3D Synthetic 3D Microstructure Dataset of Single Crystal FCC Copper

description: The MatViz3D Microstructure Mechanics Dataset is a curated collection of fully parameterized 3D polycrystalline microstructures (Representative Volume Elements, RVEs) designed for research in computational materials science, micromechanics, and machine-learning-based surrogate modeling. Each dataset sample is generated, simulated, and post-processed automatically within the MatViz3D framework, following a closed-loop workflow that integrates microstructure generation, FEM simulation in ANSYS, and structured data serialization in HDF5 format.

The dataset provides both geometric descriptors of microstructures and high-fidelity mechanical response fields (stress, strain, and displacement tensors), enabling the development and validation of deep learning models for field regression, materials homogenization, failure prediction, and structure–property mapping.

Project links





Official website: MatViz3D




GitHub repository: https://github.com/MME-NTU-KhPI/MatViz3D



Content and Structure

Each sample corresponds to a single RVE stored as an individual HDF5 (.hdf5) file, named according to its generation parameters (e.g., result-5-5.hdf5). The internal structure follows FAIR principles and ICME community standards for numerical materials data storage.

Every file contains several logically separated groups:

1. geometry/

Contains all information required to reconstruct the polycrystalline 3D mesh:





nodes: array of shape (N, 3) with node coordinates (X, Y, Z)




elements: connectivity list of finite elements




grain_id: mapping of nodes/elements to grain indices




grain_stats: statistical descriptors (grain size, orientation, morphology)



These data encode the geometric and topological structure of each microstructure.

2. eps_as_loading/

Stores the macroscopic loading tensor applied as boundary conditions during FEM simulation:





EpsXX, EpsYY, EpsZZ




EpsXY, EpsYZ, EpsXZ



This tensor serves as the input condition for the mechanical simulation and can be used as conditioning information in ML tasks.

3. results/

The main group containing per-node mechanical fields returned from ANSYS:





Nodal coordinates: X, Y, Z




Displacement vectors: UX, UY, UZ




Stress tensor components:





SX, SY, SZ




SXY, SYZ, SXZ






Strain tensor components:





EpsX, EpsY, EpsZ




(and shear strains where available)





These datasets represent the high-resolution ground-truth mechanical response for each RVE.

4. results_avg/, results_max/, results_min/

Precomputed aggregated statistics for fast screening and ML-based homogenization:





average stress and strain invariants




peak stress values




summary deformation metrics




reduced descriptors for coarse-scale surrogate models



These summary groups eliminate the need to load full per-node fields when only global properties are required.

Generation Workflow

The dataset was produced using an automated pipeline:





Microstructure generation (MatViz3D)Procedural grain generation with controlled grain size, orientation, and morphology.




FEM simulation (ANSYS)Mesh creation, boundary condition enforcement, and solution of the elastic boundary-value problem.




Data ingestion and structuring (MatViz3D)Import of ANSYS results, alignment with grain topology, and HDF5 serialization using hierarchical data groups.



This ensures reproducibility, data integrity, and strict correspondence between geometry and mechanical response.

Applications

The dataset is intended for research in:





surrogate modeling of stress/strain fields




structure–property prediction




deep learning for tensor fields




physics-informed neural networks




microstructure-sensitive materials design




computational homogenization




validation of grain-scale and voxel-scale micromechanics models



Because the dataset includes both microstructural geometry and full-field FEM solutions, it is well-suited for training neural networks that require physically consistent mappings between spatial structure and mechanical behavior.

File Format

All data are stored in HDF5, ensuring:





efficient hierarchical organization




compatibility with Python, MATLAB, C/C++, and ML frameworks




fast partial access to large simulation outputs (e.g., per-grain stress fields)




compact binary storage of floating-point tensors



The use of HDF5 follows modern standards for ICME data exchange and FAIR scientific data practices.

Software Ecosystem & Scripts

The dataset is supported by a specialized Python-based software ecosystem designed for data integrity, post-processing, and high-level statistical analysis. These scripts facilitate the transition from raw FEM outputs to structured mechanical property distributions.

1. HDF5Operator.py (Data Management)

This utility serves as a core wrapper for the h5py library, ensuring consistent data handling across the pipeline.





Key Features: Provides high-level methods for writing, reading, and listing datasets.




Reliability: Implements a rewrite_data method that safely updates existing records, ensuring that experimental results or calculated matrices can be iteratively refined without file corruption.



2. mv3d_post.py (Mechanical Post-Processing)

A critical component for converting nodal FEM results into homogenized material properties.





Tensor Calculation: Uses a least-squares approach (np.linalg.lstsq) to solve for the full 6x6 Stiffness (C) and Compliance (S) matrices based on multiple loading cases.




Validation & Quality Control: Features a robust validation engine (check_strain_error) that verifies if the average nodal strains match the prescribed boundary conditions. It uses configurable thresholds (Absolute Tolerance: 1e-4, Relative Error: 5%) to skip or flag inconsistent simulation steps.




Visualization: Includes functions to visualize the generated tensors as heatmaps using matplotlib, formatted in standard Voigt notation.



3. load_modulus_dataset.py (Statistical Analysis & Reporting)

The top-level script for large-scale dataset characterization and machine learning preparation.





Property Extraction: Automatically iterates through HDF5 files to extract Young’s Modulus (E), Shear Modulus (G), and Poisson’s Ratio (ν) components.




Advanced Statistics: Beyond basic mean and standard deviation, it calculates the 3rd and 4th statistical moments (Skewness and Kurtosis) to characterize the distribution of mechanical properties across the microstructure ensemble.




Automated Plotting: Generates publication-ready histograms with fitted Normal Distribution PDFs and matrix visualizations for effective material constants.




Export: Saves processed results into structured .csv files for further use in training surrogate models or performing uncertainty quantification.