Tutorial Useful Tools

Tutorial: Useful Tools

This page summarizes the most important practical scripts from tools/. Check these files' docs for further details.

1. resize_array_variables.py (most important)

Use this when changing dimensional constants such as N_CELL_TYPES and N_SPECIES.

What it does:

• updates model.py dimensions
• resizes known per-type/per-species arrays
• updates matching hard-coded constants in .cpp files
• creates backups of edited files

Examples:

python tools/resize_array_variables.py --species 4
python tools/resize_array_variables.py --cell-types 4
python tools/resize_array_variables.py --cell-types 4 --species 4 --dry-run

2. check_hard_coded_values.py

This script checks consistency between literal constants in model.py and values repeated in Python/C++ files.

It is also called automatically by model.py during startup.

Example:

python check_hard_coded_values.py 

Use it after major parameter-structure edits or merge conflicts.

The default asks before repairing mismatches. For a read-only check of the core and an active variant:

python check_hard_coded_values.py --scan-root . --scan-root variants/radial_glia --no-recursive --fail-on-mismatch

Exit codes are 0 for consistent values or completed repairs, 2 for unrepaired mismatches, and 1 for a reference/scan/repair error. --fail-on-mismatch never prompts or writes. Replace it with --fix to explicitly repair without prompting; the two flags cannot be combined. Without scan options, the standalone checker scans recursively, including other variants. Model startup and optimizer preflight instead scan core files and the selected variant's immediate files (or just the selected legacy flat module).

The optimizer runs this read-only check before launching trials, using literals in core model.py. It also stops the study if a trial fails model validation/execution, produces no pickle, or cannot evaluate its objective. Details remain in the trial's stdout.log and stderr.log.

3. benchmark_perf.py

Runs performance sweeps over combinations such as N, N_CELLS, FOCAD count, and optional networks.

Quick example:

python tools/benchmark_perf.py --steps 10 --dry-run

See full guide: Tutorial: Benchmarking Performance.

4. check_pickle.py

Prints a structured summary of an output pickle (top-level keys, dataframe shapes, sample rows).

Example:

python tools/check_pickle.py --pickle result_files/output_data_0.pickle

5. inspect_pickle_key.py

Loads a specific key from a pickle and drops into breakpoint() for manual debugging.

Example:

python tools/inspect_pickle_key.py result_files/output_data_0.pickle --key CELL_METRICS_OVER_TIME --expect-df

Best used in debug mode from an IDE/terminal debugger session.

6. delete_optuna_study.py

Utility script to remove one Optuna study from an SQLite storage without deleting other studies in the same database.

Typical workflow:

1. Edit storage and study_name in the script.
2. Run:

python tools/delete_optuna_study.py

Useful when one comparative study is invalid but other studies in the same DB must be kept.

7. generate_vascular_network.py

Generates a random connected vascular network inside user-defined cuboidal bounds and saves it as a pickle (optionally VTK).

Example:

python tools/generate_vascular_network.py --bounds 50 -50 50 -50 50 -50 --diameter 5 --density 0.02 --resolution 5 --branching-probability 0.08 --nucleation-faces 1 1 0 0 0 0 --nucleation-per-face 8 --seed 1 --output vascular_network.pickle --save-vtk

8. param_ui.py

Desktop parameter editor for model.py built with PySide6. It helps edit and run with less manual source editing.

Run:

python tools/param_ui.py

See: Model Editor.

9. remove_anchors_from_cell_vtks.py

Creates simplified VTK cell files without anchor points by trimming each cells_t*.vtk according to output_data_0.pickle cell counts.

Example:

python tools/remove_anchors_from_cell_vtks.py --input-dir result_files

Output files are named like no_anchor_cells_tXXXX.vtk.