negu93/cvnn

1. What this repository is

- cvnn is a TensorFlow/Keras extension for building complex-valued neural networks using native complex dtypes.

- The package is designed so the outer training loop stays standard Keras: compile(), fit(), evaluate(). The main architectural change is swapping tf.keras.layers for cvnn.layers.

2. Core runtime boundary

- The package is a Python library, not an application server.

- TensorFlow is the execution backend; cvnn adds complex-aware layers, activations, initializers, losses, and metrics on top of TensorFlow/Keras.

- The README makes an important boundary explicit: the final model output must be converted to real values for losses to work, since the loss cannot minimize a complex number directly.

3. Primary package surface

- cvnn/__init__.py exposes the package API, while cvnn/__main__.py and cvnn/cli.py provide a command-line entrypoint.

- cvnn/_version.py and versioneer.py indicate versioning is automated and integrated into packaging/release workflows.

4. Layer subsystem

- cvnn/layers/ is the main architectural core.

- It is split into:

- core.py for dense/input-style building blocks,

- convolutional.py for complex convolutions and transposed convolutions,

- pooling.py for complex pooling/unpooling-style operations,

- upsampling.py for complex upsampling.

- These layers are the main replacement boundary for Keras layers in user models.

5. Activation subsystem

- cvnn/activations.py holds complex-valued activation functions and output transforms.

- The docs show several activation families, including Cartesian-style activations and functions that map complex outputs back to real space.

- This module is central to the model’s end-to-end data flow because activations are used both inside hidden layers and at the final output to satisfy real-valued loss requirements.

6. Initialization and parameter setup

- cvnn/initializers.py provides complex-aware weight initialization strategies.

- The docs reference variants analogous to common Keras initializers such as Glorot and He, but adapted for complex-valued parameters.

- This subsystem matters because complex weights need initialization rules that preserve signal scale differently from purely real networks.

7. Training objectives and evaluation

- cvnn/losses.py and cvnn/metrics.py adapt training objectives and reporting to the complex setting.

- The library’s architecture assumes a common pattern: complex feature extraction through the network, then a real-valued final representation for the loss/metric layer.

- cvnn/tb.py likely contains TensorBoard-related helpers, suggesting an observability boundary for training runs.

8. Utilities and theoretical helpers

- cvnn/utils.py and cvnn/real_equiv_tools.py support data conversion, model analysis, or real-equivalent comparisons.

- The presence of real_equiv_tools.py suggests a distinct concern: comparing complex networks against real-valued equivalents for validation or research analysis.

9. Documentation and research artifacts

- docs/ is a full Sphinx documentation tree with built HTML output already checked in.

- It includes dedicated pages for layers, activations, initializers, losses, metrics, optimizers, Monte Carlo analysis, and example notebooks.

- This repo is research-oriented: documentation is not just API reference, but also experiment reports and generated analysis artifacts.

10. Examples and validation flow

- examples/ contains end-user model scripts/notebooks for CIFAR, Fashion-MNIST, MNIST, U-Net, and regression-style demos.

- These examples illustrate the intended flow: convert or supply complex data, build a model from cvnn.layers, train with standard Keras, and inspect results.

- debug/ contains ad hoc notebooks/scripts for investigating gradients, memory, FFT behavior, and learning stability.

11. Test architecture

- tests/ is broad and maps closely to the package surface: activation functions, custom layers, initialization, dataset conversion, losses, metrics, dtype behavior, functional API, dropout, and comparison against TensorFlow behavior.

- This indicates the architecture is validated at the API contract level rather than through a single end-to-end app test.

12. Packaging and distribution

- setup.py, setup.cfg, MANIFEST.in, conda.recipe/, and appveyor.yml show the project is distributed as a Python package and supports both pip and conda workflows.

- readthedocs.yml and the checked-in docs build outputs show documentation is part of the release footprint.

- Overall, the repo is organized as a reusable scientific library with clear separations between core TensorFlow extensions, research analysis, documentation, and test coverage.