Metadata-Version: 2.4
Name: ncalab
Version: 0.2.0
Summary: Training code and pre-trained models for Neural Cellular Automata on different datasets and tasks
License-Expression: MIT
Project-URL: Documentation, https://ncalab.readthedocs.io/en/latest/
Project-URL: Repository, https://github.com/MECLabTUDA/NCAlab
Classifier: Programming Language :: Python :: 3.12
Classifier: Development Status :: 3 - Alpha
Requires-Python: >=3.12
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: absl-py==2.2.2
Requires-Dist: albucore==0.0.24
Requires-Dist: albumentations==2.0.8
Requires-Dist: annotated-types==0.7.0
Requires-Dist: asttokens==3.0.0
Requires-Dist: astunparse==1.6.3
Requires-Dist: certifi==2025.4.26
Requires-Dist: charset-normalizer==3.4.2
Requires-Dist: click==8.1.8
Requires-Dist: comm==0.2.2
Requires-Dist: contourpy==1.3.2
Requires-Dist: cycler==0.12.1
Requires-Dist: debugpy==1.8.14
Requires-Dist: decorator==5.2.1
Requires-Dist: numpy==2.1.3
Requires-Dist: torch==2.7.1
Requires-Dist: tqdm==4.67.1
Requires-Dist: emoji==2.14.1
Requires-Dist: etils==1.12.2
Requires-Dist: eval-type-backport==0.2.2
Requires-Dist: executing==2.2.0
Requires-Dist: filelock==3.18.0
Requires-Dist: fire==0.7.0
Requires-Dist: flatbuffers==25.2.10
Requires-Dist: fonttools==4.57.0
Requires-Dist: fsspec==2025.3.2
Requires-Dist: gast==0.6.0
Requires-Dist: google-pasta==0.2.0
Requires-Dist: grpcio==1.72.0
Requires-Dist: gviz-api==1.10.0
Requires-Dist: h5py==3.12.1
Requires-Dist: idna==3.10
Requires-Dist: imageio==2.37.0
Requires-Dist: importlib-resources==6.5.2
Requires-Dist: iniconfig==2.1.0
Requires-Dist: ipython==8.31.0
Requires-Dist: jedi==0.19.2
Requires-Dist: jinja2==3.1.6
Requires-Dist: joblib==1.4.2
Requires-Dist: keras==3.11.0
Requires-Dist: keras-applications==1.0.8
Requires-Dist: kiwisolver==1.4.8
Requires-Dist: lazy-loader==0.4
Requires-Dist: libclang==18.1.1
Requires-Dist: markdown==3.8
Requires-Dist: markdown-it-py==3.0.0
Requires-Dist: markupsafe==3.0.2
Requires-Dist: matplotlib==3.10.1
Requires-Dist: matplotlib-inline==0.1.7
Requires-Dist: mdurl==0.1.2
Requires-Dist: medmnist==3.0.2
Requires-Dist: ml-dtypes==0.5.1
Requires-Dist: mpmath==1.3.0
Requires-Dist: munch==4.0.0
Requires-Dist: mypy==1.15.0
Requires-Dist: mypy-extensions==1.1.0
Requires-Dist: namex==0.0.9
Requires-Dist: nest-asyncio==1.6.0
Requires-Dist: networkx==3.4.2
Requires-Dist: onnx==1.17.0
Requires-Dist: onnxscript==0.2.5
Requires-Dist: opencv-python-headless==4.11.0.86
Requires-Dist: opt-einsum==3.4.0
Requires-Dist: optree==0.15.0
Requires-Dist: packaging==25.0
Requires-Dist: pandas==2.2.3
Requires-Dist: pandas-stubs==2.2.3.250308
Requires-Dist: parso==0.8.4
Requires-Dist: pexpect==4.9.0
Requires-Dist: pillow==11.3.0
Requires-Dist: platformdirs==4.3.7
Requires-Dist: pluggy==1.5.0
Requires-Dist: pretrainedmodels==0.7.4
Requires-Dist: prompt-toolkit==3.0.51
Requires-Dist: protobuf==4.25.8
Requires-Dist: psutil==7.0.0
Requires-Dist: ptyprocess==0.7.0
Requires-Dist: pure-eval==0.2.3
Requires-Dist: pydantic==2.11.4
Requires-Dist: pydantic-core==2.33.2
Requires-Dist: pygments==2.19.1
Requires-Dist: pyparsing==3.2.3
Requires-Dist: pytest==8.3.5
Requires-Dist: python-dateutil==2.9.0.post0
Requires-Dist: pytorch-msssim==1.0.0
Requires-Dist: pytz==2024.2
Requires-Dist: pyyaml==6.0.2
Requires-Dist: pyzmq==26.4.0
Requires-Dist: regex==2024.11.6
Requires-Dist: requests==2.32.4
Requires-Dist: rich==14.0.0
Requires-Dist: safetensors==0.5.3
Requires-Dist: scikit-image==0.25.2
Requires-Dist: scikit-learn==1.6.1
Requires-Dist: scipy==1.15.2
Requires-Dist: seaborn==0.13.2
Requires-Dist: semver==3.0.4
Requires-Dist: setuptools==80.1.0
Requires-Dist: simsimd==6.2.1
Requires-Dist: six==1.17.0
Requires-Dist: stack-data==0.6.3
Requires-Dist: stringzilla==3.12.5
Requires-Dist: sympy==1.14.0
Requires-Dist: tensorboard==2.19.0
Requires-Dist: tensorboard-data-server==0.7.2
Requires-Dist: tensorboard-plugin-profile==2.19.4
Requires-Dist: tensorflow==2.19.0
Requires-Dist: termcolor==3.1.0
Requires-Dist: threadpoolctl==3.6.0
Requires-Dist: tifffile==2025.3.30
Requires-Dist: tokenizers==0.21.1
Requires-Dist: torch-tb-profiler==0.4.3
Requires-Dist: torchvision==0.22.1
Requires-Dist: tornado==6.5
Requires-Dist: traitlets==5.14.3
Requires-Dist: transformers==4.53
Requires-Dist: types-pytz==2025.2.0.20250326
Requires-Dist: types-requests==2.32.0.20250328
Requires-Dist: types-tqdm==4.67.0.20250417
Requires-Dist: typing-extensions==4.13.2
Requires-Dist: tzdata==2025.2
Requires-Dist: urllib3==2.5.0
Requires-Dist: wcwidth==0.2.13
Requires-Dist: werkzeug==3.1.3
Requires-Dist: wheel==0.46.1
Requires-Dist: wrapt==1.17.2
Requires-Dist: zipp==3.21.0
Requires-Dist: sphinx-autoapi>=3.6.0
Requires-Dist: aiohappyeyeballs==2.6.1
Requires-Dist: aiohttp==3.12.14
Requires-Dist: attrs==25.3.0
Requires-Dist: build==1.2.2.post1
Requires-Dist: cachetools==5.5.2
Requires-Dist: cheroot==10.0.1
Requires-Dist: colorclass==2.2.2
Requires-Dist: docopt==0.6.2
Requires-Dist: frozenlist==1.6.0
Requires-Dist: gcsfs==2025.3.2
Requires-Dist: jaraco-functools==4.1.0
Requires-Dist: more-itertools==10.7.0
Requires-Dist: multidict==6.4.3
Requires-Dist: nvidia-cublas-cu12==12.6.4.1
Requires-Dist: nvidia-cuda-cupti-cu12==12.6.80
Requires-Dist: nvidia-cuda-nvrtc-cu12==12.6.77
Requires-Dist: nvidia-cuda-runtime-cu12==12.6.77
Requires-Dist: nvidia-cudnn-cu12==9.5.1.17
Requires-Dist: nvidia-cufft-cu12==11.3.0.4
Requires-Dist: nvidia-cufile-cu12==1.11.1.6
Requires-Dist: nvidia-curand-cu12==10.3.7.77
Requires-Dist: nvidia-cusolver-cu12==11.7.1.2
Requires-Dist: nvidia-cusparse-cu12==12.5.4.2
Requires-Dist: nvidia-cusparselt-cu12==0.6.3
Requires-Dist: nvidia-nccl-cu12==2.26.2
Requires-Dist: nvidia-nvjitlink-cu12==12.6.85
Requires-Dist: nvidia-nvtx-cu12==12.6.77
Requires-Dist: oauthlib==3.2.2
Requires-Dist: pip-tools==7.4.1
Requires-Dist: pip-upgrader==1.4.15
Requires-Dist: propcache==0.3.1
Requires-Dist: proto-plus==1.26.1
Requires-Dist: pyasn1==0.6.1
Requires-Dist: pyasn1-modules==0.4.2
Requires-Dist: pyproject-hooks==1.2.0
Requires-Dist: requests-oauthlib==2.0.0
Requires-Dist: rsa==4.9.1
Requires-Dist: terminaltables==3.1.10
Requires-Dist: typing-inspection==0.4.0
Requires-Dist: yarl==1.20.0
Requires-Dist: cfgv==3.4.0
Requires-Dist: distlib==0.3.9
Requires-Dist: identify==2.6.10
Requires-Dist: nodeenv==1.9.1
Requires-Dist: pre-commit==4.2.0
Requires-Dist: virtualenv==20.30.0
Requires-Dist: sphinx==8.1.3
Requires-Dist: sphinx-rtd-theme>=3.0.2
Requires-Dist: plyfile>=1.1
Requires-Dist: twine>=6.1.0
Requires-Dist: ruff>=0.12.4
Requires-Dist: torchmetrics>=1.7.4
Requires-Dist: segmentation-models-pytorch>=0.5.0
Dynamic: license-file

# NCALab

NCALab makes it easy to create Neural Cellular Automata (NCA) implementations for various downstream tasks, such as image segmentation, classification and synthesis.


![docs](https://github.com/MECLabTUDA/NCAlab/actions/workflows/docs.yml/badge.svg)
![python-package](https://github.com/MECLabTUDA/NCAlab/actions/workflows/python-package.yml/badge.svg)
![manuscript](https://github.com/MECLabTUDA/NCAlab/actions/workflows/draft-pdf.yml/badge.svg)

![NCALab Logo](artwork/ncalab_logo.png)


## Features

Features of NCALab include:
  * Easy training and evaluation of NCA models
  * Cascaded multi-scale training
  * Tensorboard integration with default presets
  * Training with k-fold cross-validation
  * Convenience features: Fixing random seeds, selecting compute devices, data processing


## Getting started

Perhaps the best way of getting started with NCALab is to take a look at the provided usage example tasks, starting with the Growing Emoji task.

### Usage Example Tasks

So far, the following example tasks are implemented in NCALab:

  * Image Generation:
    * Growing NCA for emoji generation
      * Training and evaluation
      * Fine-tuning of a pre-trained emoji generator
      * Hyperparameter search
  * Image Classification:
    * Self-classifying MNIST digits
    * MedMNIST image classification (PathMNIST, BloodMNIST, DermaMNIST)
  * Image Segmentation:
    * Endoscopic polyp segmentation (Kvasir-SEG, public)


You can find those example tasks inside the `tasks/` directory and its subfolders.


### Growing Lizard Example

A good starting point to get started with NCAs is the famous Growing Lizard emoji example.


```bash
uv run tasks/growing_emoji/train_growing_emoji.py
```


Run this script to generate a GIF of the trained model's prediction:

```bash
uv run tasks/growing_emoji/eval_growing_emoji.py
```

![Animation of a growing lizard emoji](artwork/growing_emoji.gif)


### Installation

Run

```bash
pip install ncalab
```

to install the latest release or

```bash
pip install git+https://github.com/MECLabTUDA/NCALab
```

for the most recent commit of NCALab.
We recommend to install NCALab in a virtual environment.


## Tensorboard integration

We recommend you to monitor your training progress in Tensorboard.
To launch tensorboard, run

```bash
uv run tensorboard --logdir=runs
```

in a separate terminal.
Once it is running, it should show you the URL the tensorboard server is running on, which is [localhost:6006](https://localhost:6006) by default.
Alternatively, you may use the tensorboard integration of your IDE.


# For Developers

Type checking:

```bash
uv run mypy ncalab
```

Static code analysis:

```bash
uv run ruff check ncalab
```

Testing:

```bash
uv run pytest
```


# How to Cite

Coming soon.
