LocalizedWaveCharacterization2D

Python code for data-driven localization region detection, segmentation and localized wave directionality estimation within the detected regions in numerical simulations of a two-dimensional (2D) hexagonal crystal lattice model. Using the code and developed methodology, please cite the preprint F. Kozirevs, J. Bajārs, Localization region detection with directionality estimation in a two-dimensional hexagonal crystal lattice model. arXiv:2606.24923 (2026). Available at: https://arxiv.org/abs/2606.24923.

The figures above show 2D hexagonal and quasi-one-dimensional (quasi-1D) data collection regions (on the left), as well as localization regions with their estimated directions (on the right) detected in a simulation of three stationary and three traveling discrete breathers (DBs) using the classifiers trained on data which was collected from the 2D hexagonal and quasi-1D regions.

This research is funded by the Latvian Council of Science, project "Development of structure- and data-driven methods for analysis and control of complex dynamical systems", project No. lzp-2024/1-0207.

Instructions to run the code

• The code was developed on Apple Silicon Mac in Conda osx-64 environment. All the required Python packages are listed in environment.yml. The repository includes shared libraries (.so) together with the corresponding C source code. To recompile the C code on other platforms, a C compiler with OpenMP support is required.
• All the generated figures are saved to the folder figures. The legends for Figures 2 and 3, as well as the explanations of all the figures, can be found in the preprint.
• All the functions used for performing numerical simulations, generating DBs, collecting lattice wave data from different regions, applying the trained classifiers together with the sliding window method and aggregating the obtained predictions, as well as for segmenting the detected localization regions and estimating localized wave directionality, are defined in the folder functions.
• In the code:
  • data_collection_region describes the type of data collection regions used: its values 2D, 1D, and q1D encode 2D hexagonal, one-dimensional, and quasi-1D regions, respectively;
  • aggregation describes if the summation (value summation) or product (value product) prediction aggregation approach is used;
  • DB_type describes if the considered DB is stationary (value 0) or traveling (value 1);
  • DB_direction (or direction) describes the direction of the considered DB: its values 0, 1, and 2 encode the directions correpsonding to $\alpha=0$, $\alpha=\pi/3$ and $\alpha=2\pi/3$, respectively;
  • Nsim is used to specify the number of crystal lattice numerical simulations performed to create a lattice wave dataset;
  • Tsim is used to specify the final computational time of a crystal lattice numerical simulation;
  • dim is used to specify the dimension number of a low-dimensional dataset which is obtained after applying Principal Component Analysis (PCA).
• All the parameter and variable values that are not defined directly in the script files are set and saved in dictionaries using parameter_values.py and variable_values.py, respectively.
• To perform numerical simulations of the crystal lattice particle dynamics, run main.py.
• To collect crystal lattice wave data, run collect_wave_data.py. The obtained datasets can be found in the folder data/training_and_test_data.
• To reduce the dataset dimensionality using PCA and train the wave-data Support Vector Machine classifiers, run classification.py. The trained classifiers, as well as the fitted PCA models and scalers, can be found in the folder classifiers.
• To analyze the trained classifier performance, run classification_precision_recall.py. The obtained performance measure values are saved to the folder classification_precision_recall_values as .txt files. The precision and recall values are also saved to the folder data/classification_precision_recall_data as .csv files.
• To plot Figures 1 and 2 from the preprint, perform the three stationary DB numerical simulation running loc_regions_simulation.py and then execute data_collection_regions_fig1a.py, data_collection_regions_fig1b.py, data_collection_regions_fig1c.py, and loc_regions_fig2.py. The simulation data is saved to the folder data/loc_regions_sim_data.
• To analyze performance of the directionality estimation algorithm, run directionality_estimation_accuracy.py. The simulation and accuracy data is saved to the folder data/directionality_estimation_acc_data. In the code, data contains the directionality estimation accuracy, and data_loc_regions contains the localization region detection accuracy (the proportion of simulation time instants at which one localization region was detected) for different shapes of the sliding windows and different values of $N_d$. To plot Figure 3 from the preprint, run directionality_estimation_accuracy_fig3.py.
• To perform a numerical simulation of six DB interactions, run numerical_study_six_DBs.py. The simulation data is saved to the folder data/numerical_study_data/six_DBs. To simulate two DB head-to-head and head-to-adjacent-head collisions, run numerical_study_H2H_collision.py and numerical_study_H2aH_collision.py, respectively. The data is saved to the folder data/numerical_study_data/H2H_collision in the former case and to the folder data/numerical_study_data/H2aH_collision in the latter case. To plot Figures 4-7 from the preprint, run numerical_study_fig4.py, numerical_study_fig5.py, and numerical_study_fig6_7.py. In the code, col describes the considered collision type: its values H2H and H2aH encode head-to-head and head-to-adjacent-head collisions, respectively.