Chordless Cycle Filtrations For Dimensionality Detection In Complex Networks

Code and released artifacts for the article Chordless cycle filtrations for dimensionality detection in complex networks via topological data analysis.

The repository contains three layers of the workflow:

• cycles/ generates synthetic S^D networks and extracts chordless-cycle statistics.
• tda_code/ converts cycle-weighted graphs into TDA feature tables.
• dimnn/ and scripts/ train models and run inference from those features.

zenodo/ is the supported source for released training tables, trained models, and real-network predictions.

Requirements

• Python 3.10 or newer
• gfortran
• g++ with Boost system and boost_math_c99

Install the Python dependencies from the repo root:

python -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
pip install -r requirements.txt

Repository Layout

• cycles/: synthetic-network generation and cycle extraction.
• tda_code/: persistence-based feature extraction from .edge_cycles files.
• scripts/: maintained CLI entrypoints for batch feature extraction and prediction, plus older legacy scripts.
• dimnn/: training and model-comparison scripts for the released feature sets.
• zenodo/: released artifacts mirrored locally.
• SD-model/ and geometric-randomization/: standalone subprojects with their own READMEs.

Canonical Workflow

1. Predict dimensions from the released real-network feature table

python -m scripts.neural_network_prediction \
  --input-csv zenodo/real_nets_properties__14_06_25.csv \
  --model-prefix zenodo/models_and_outputs/adamw_columns_n_k_k2_kmin_kmax_knn_Ci_TPi \
  --output-csv zenodo/real_nets_properties__14_06_25_predictions.csv

2. Predict the dimension of a single edge list

python -m scripts.predict_dimension \
  --edge-file path/to/network.edge \
  --model-prefix zenodo/models_and_outputs/adamw_columns_n_k_k2_kmin_kmax_knn_Ci_TPi

This command compiles cycles/compute_edgecycles.for into .build/, extracts cycle weights for the input graph, computes the TDA features, and runs the released classifier bundle.

3. Compute feature tables for a folder of edge lists

python -m scripts.compute_properties \
  --edge-dir path/to/edge_lists \
  --output-csv real_network_features.csv

The resulting CSV can be passed to scripts.neural_network_prediction.

4. Retrain the released classifier on the Zenodo training table

python -m dimnn.neural_network_training_clean \
  --data zenodo/data_for_training_new_04_04_25.csv \
  --output-dir models_and_outputs

Related training entrypoints:

• python -m dimnn.neural_network_training_mlp --data zenodo/data_for_training_new_04_04_25.csv --output-dir models_and_outputs_MLP
• python -m dimnn.neural_network_training_regressor --data zenodo/data_for_training_new_04_04_25.csv --output-dir models_and_outputs_regression
• python -m dimnn.retraining_agreement --data zenodo/data_for_training_new_04_04_25.csv --output-dir models_and_outputs_comparison

5. Compare classifier and regressor outputs on released artifacts

python -m dimnn.comparison_models_real_data \
  --training-data zenodo/data_for_training_new_04_04_25.csv \
  --real-data zenodo/real_nets_properties__14_06_25.csv \
  --classifier-prefix zenodo/models_and_outputs/adamw_columns_n_k_k2_kmin_kmax_knn_Ci_TPi \
  --regressor-prefix zenodo/models_and_outputs_regression/regression_columns_n_k_k2_kmin_kmax_knn_Ci_TPi

From-Scratch Synthetic Pipeline

Generate synthetic S^D networks from the example configuration:

python -m cycles.generate_SD_networks_parallel config/SD_example.yaml output/sd_networks

Extract cycle statistics and .edge_cycles files:

python -m cycles.run_compute_edgecycles_parallel \
  --input-dir output/sd_networks \
  --output-dir output/sd_cycles

Convert the .edge_cycles files into one CSV per network:

python -m tda_code.main_server \
  --input-dir output/sd_cycles \
  --output-dir Results_tda

Merge the per-network CSV files into a single training table:

python -m scripts.merge_tda_csv_files \
  --input-glob 'Results_tda/*.csv' \
  --output-csv data_for_training.csv

Train a model from the merged table:

python -m dimnn.neural_network_training_clean \
  --data data_for_training.csv \
  --output-dir models_and_outputs

Released Artifacts

The data and models released are available on Zenodo at https://zenodo.org/records/19470037.

Reference

Chordless cycle filtrations for dimensionality detection in complex networks via topological data analysis
Aina Ferrà Marcús, Robert Jankowski, Meritxell Vila Miñana, Carles Casacuberta, M. Ángeles Serrano
Nature Communications, 2026 (accepted)
arXiv