Modelling results for 3D Framework exploring hydrothermal weakening of lava domes

This repository contains the full 3D numerical model output files (DEM model), associated strain data and visualisation tools supporting the research presented in the paper: From Alteration to Avalanche: A 3D Framework for Exploring Hydrothermal Weakening of Lava Domes, K.D. Ní Nualláin et al., 2026, submitted to Journal of Volcanology and Geothermal Research. While the manuscript presents 2D cross-sections of the stability models, this repository provides the complete 3D datasets to allow readers to explore the spatial distribution of displacement and strain within the lava dome. Additionally, this repository includes a novel custom visualisation framework developed in Python to render these large-scale particle datasets in 3D. First, the repository is organised into two main archives: Displacement.zip contains raw displacement text files exported from Particle Flow Code (PFC). These files track the initial and final positions of particles; Strain.zip contains strain tensor output files. Strain was calculated using a local deformation gradient approach via MATLAB and exported for visualisation. The method is described in the paper in Section 3.6. Secondly, two pdf documents are available: Resource_Tool_3D_PFC_Plotting_Displacements.pdf: Guide and code for plotting particle displacement vectors; Resource_Tool_3D_PFC_Plotting_Strain.pdf: Guide and code for plotting maximum shear strain. Naming convention Folders and files respect a naming convention according to the different scenarios used in the study. For example: Het_Collapse_Bulge_10%_150m_TopDown_10000_Displacement/Het_Collapse_Bulge_10%_150m_TopDown_10000x_y.txt The used naming template is AAA_BBB_CCC_DDD_EEE_FFF_GGG_HHH. AAA is the Heterogeneous/homogeneuous code. Het (Heterogeneous): Represents a model with a heterogeneous distribution of rock strength/alteration throughout the dome. BBB is the model code: collapse. However, Listric (Structural Control) is a specific instability model used in the Discussion section. This geometry was defined to match the low-resistivity structures identified in the Electrical Resistivity Tomography (ERT) surveys. CCC is the weakened zone code. It can be the Bulge or the whole southern flank of the lava dome. See the manuscript for further details. DDD is the numeric suffix indicating the residual strength percentage relative to the unaltered host rock: _10_: Rock strength is reduced to 10% of the host rock strength; _50_: Rock strength is reduced to 50% of the host rock strength. (Example: Top_Down_10 indicates deep alteration where the rock mass strength is reduced to 10% of its original value.) EEE is the depth of mechanically weakened zone (i.e., due to hydrothermal alteration). FFF represents a scenario via Top_Down or Surface_Alt codes. Top_Down (Deep Weakening) represents a scenario where mechanical rock weakening extends from the surface down to a depth of EEE. Surface_Alt (Shallow/Surficial Weakening) represents a scenario restricted to surficial rock weakening, extending to a depth in EEE. GGG is the numbers of cycles (calculcation iterations of the DEM models). HHH is the key file. For folders, the result family is noticed (i.e., displacement or strain). For files, the key represents the result values (i.e., position for x_y key). Visualisation Workflow Standard visualisation tools often struggle with the density of particle data exported from PFC. The provided tools use the Mayavi scientific data visualiser in Python to efficiently render these datasets. To run the provided scripts, the following Python libraries are required: mayavi, vtk, pandas, numpy, matplotlib, seaborn. Quick Start: Prepare the Data: Ensure the PFC text outputs (which may be split into columns) are concatenated as described in the Resource_Tool PDFs; Load the Environment: It is recommended to create and use a Conda environment for Mayavi installation (conda install mayavi); Run the Script: The scripts enable the creation of cross-sections, full 3D views, or "boreholes" (cropping along axes) to inspect internal deformation—features used heavily in the paper's analysis. Citation If you use this data or the visualisation tools in your own work, please cite the associated paper and this repository. Ní Nualláin, K.D. (2026). From Alteration to Avalanche: A 3D Framework for Exploring Hydrothermal Weakening of Lava Domes. Add the link of this Zenodo repo.