Reproduction Process

GDKVM: Echocardiography Video Segmentation via Spatiotemporal Key-Value Memory with Gated Delta Rule

1. Environment Setup

0. Clean Environment

If a virtual environment is currently activated in your Shell (indicated by (base) or (env) on the left), please deactivate it first.

For Conda environments:

conda deactivate

For standard venv:

deactivate

Note: uv's environment management features high isolation. In most scenarios, even without deactivating the Conda environment, directly creating a uv virtual environment will not cause dependency conflicts.

1. Preparation: Install uv

This project uses uv for dependency management. Developed in Rust, it features highly efficient dependency resolution capabilities.

Installation without direct internet access:

pip install uv

Or update to the latest version:

pip install --upgrade uv

Verify installation:

uv -V

Baseline version: Today's version 0.9.10.

2. Get Project Code

Clone the repository and specify the local directory name.

git clone https://github.com/wangrui2025/GDKVM.git gdkvm_20251215

Enter the project directory:

cd gdkvm_20251215

Project structure overview:

.
├── .python-version    # Specifies the Python version
├── pyproject.toml     # Main project configuration file
├── uv.lock            # Lock file (Ensures consistency)
└── ...                # Other source code files

3. Initialization & Sync

uv will read configuration files, create a virtual environment, and install all dependencies.

For a newer environment, you can use the env_02 configuration. Refer to env/env_02/pyproject.toml.

uv sync

Troubleshooting: Python Installation in Intranet

Scenario: If uv sync fails (e.g., SSL errors, timeouts), it is usually due to network policies preventing uv from automatically downloading the Python interpreter.

Solution: Manually install Python via a mirror source.

Check available versions:

uv python list

Install via mirror (e.g., 3.12.12):

uv python install 3.12.12 --mirror https://github-proxy.lixxing.top/https://github.com/astral-sh/python-build-standalone/releases/download

After successful installation, run uv sync again.

Version Constraints & Compatibility

Pydantic Version Conflict <2.12

Issue: Pydantic 2.12+ (2025-10) strict Schema validation conflicts with wandb field declarations, potentially causing crashes in multi-process modes.

Solution: The configuration file forcefully locks pydantic<2.12.
Wandb System Compatibility (glibc)

Issue: wandb>=0.22.2 stopped providing pre-built packages for Ubuntu 18.04 (glibc 2.27), causing installation failures.

Solution: Ensure a Go compiler is installed for source compilation, or upgrade the OS.
SSL/TLS Certificate Errors
Issue: uv add/sync fails (Certificate Expired) because self-signed certificates in intranet/proxy environments are not trusted by uv's default Rust TLS.

Solution: Switch to system-native TLS validation.
Option A (Temporary)
```
uv add wandb --native-tls
```
Option B (Recommended)
```
export UV_NATIVE_TLS=1
```
* Recommended to add this to ~/.bashrc or ~/.zshrc

4. Activate Environment

source .venv/bin/activate

Note: Explicit activation is recommended to enable interactive debugging (e.g., Python REPL) and checking package status via pip.

Verify environment (should output the path inside project .venv):

which python

Example Output:
/data/Anon/Repo/gdkvm_20251215/.venv/bin/python

2. Data Preparation

We utilize the CAMUS and EchoNet-Dynamic datasets.

Dataset Download

Processed Data: CAMUS HuggingFace EchoNet-Dynamic todo

Raw Data: CAMUS Official HuggingFace Mirror EchoNet-Dynamic Official Mirror

3. Training & Evaluation

3.1 Model Training

1. Configuration

Select the appropriate train.sh script based on your Shell environment (zsh or bash), and configure the following environment variables to adapt to your hardware:

CUDA_VISIBLE_DEVICES: 0,1 # Specify GPU device IDs
MASTER_PORT: 29500        # Port for distributed training

2. Hyperparameters

Edit config/config_gdkvm_01.yaml to adjust key hyperparameters:

data_path: /data/Anon/dataset/camus_png256x256_10f_20250709/   # Dataset path
batch_size: 8                                                  # Batch size
learning_rate: 1.0e-4                                          # Learning rate
num_iterations: 3000                                           # Total iterations
eval_stage:
  num_vis: 0                                                   # Visualization count
  wandb_mode: "offline"                                        # Set to "offline"

3. Execute Training

Grant execution permission:

chmod +x ./train.sh

Start training:

./train.sh

3.2 Outputs

Artifacts (weights, visualizations) are saved to the directory specified in hydra.run.dir.

gdkvm_20251215/outputs

3.3 WandB Monitoring

Experiments use Weights & Biases (WandB) for offline logging.

Log Path: gdkvm_20251215/wandb
Run Directory: Subfolders with timestamps and hashes (e.g., offline-run-20251215_123456-abcdef1gh).

Upload Offline Logs

After training, sync offline data to WandB cloud:

wandb sync gdkvm_20251215/wandb/offline-run-20251215_123456-abcdef1gh