# negu93/cvnn architecture

> Architecture diagram of the GitHub repository negu93/cvnn, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-17). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/negu93/cvnn
- Repository: https://github.com/negu93/cvnn

## Overview

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.

Main entry points: [`cvnn/activations.py`](https://github.com/negu93/cvnn/blob/master/cvnn/activations.py) (Activations), [`cvnn/layers`](https://github.com/negu93/cvnn/tree/master/cvnn/layers) (Layers), [`cvnn/__init__.py`](https://github.com/negu93/cvnn/blob/master/cvnn/__init__.py) (cvnn API), [`tests`](https://github.com/negu93/cvnn/tree/master/tests) (Tests)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_g1["Package API"]
  node_n1["cvnn API<br/>package api<br/>[__init__.py]"]
  node_n2["CLI<br/>entrypoint<br/>[cli.py]"]
  node_n3["Main entry<br/>module entry<br/>[__main__.py]"]
  node_n4["Versioning<br/>release metadata<br/>[_version.py]"]
end

subgraph group_g2["Model Core"]
  node_n5["Layers"]
  node_n6["Dense & input<br/>layer submodule<br/>[core.py]"]
  node_n7["Convolutions<br/>layer submodule<br/>[convolutional.py]"]
  node_n8["Pooling<br/>layer submodule<br/>[pooling.py]"]
  node_n9["Upsampling<br/>layer submodule<br/>[upsampling.py]"]
  node_n10["Activations<br/>[activations.py]"]
  node_n11["Initializers<br/>weight init<br/>[initializers.py]"]
  node_n12["Losses<br/>training objective<br/>[losses.py]"]
  node_n13["Metrics<br/>[metrics.py]"]
  node_n14["TensorBoard<br/>training observability<br/>[tb.py]"]
  node_n15["Utils<br/>support utilities<br/>[utils.py]"]
  node_n16["Real equivalence<br/>analysis tools"]
end

subgraph group_g3["Research & Docs"]
  node_n17["Examples<br/>usage demos"]
  node_n18["Docs"]
  node_n19["Debug notebooks<br/>ad hoc experiments"]
end

subgraph group_g4["Validation & Release"]
  node_n20["Tests"]
  node_n21["Packaging<br/>distribution config<br/>[setup.py]"]
end

node_n1 -->|"exposes"| node_n5
node_n1 -->|"exposes"| node_n10
node_n1 -->|"exposes"| node_n11
node_n1 -->|"exposes"| node_n12
node_n1 -->|"exposes"| node_n13
node_n2 -->|"uses"| node_n1
node_n3 -->|"launches"| node_n2
node_n4 -->|"feeds"| node_n21
node_n5 -->|"contains"| node_n6
node_n5 -->|"contains"| node_n7
node_n5 -->|"contains"| node_n8
node_n5 -->|"contains"| node_n9
node_n6 -->|"depends on"| node_n11
node_n6 -->|"uses"| node_n10
node_n7 -->|"depends on"| node_n11
node_n8 -->|"uses"| node_n10
node_n9 -->|"uses"| node_n10
node_n10 -->|"feeds"| node_n12
node_n10 -->|"feeds"| node_n13
node_n15 -->|"supports"| node_n16
node_n16 -->|"documents"| node_n18
node_n17 -->|"builds with"| node_n5
node_n17 -->|"configures"| node_n10
node_n17 -->|"trains with"| node_n12
node_n18 -->|"documents"| node_n5
node_n18 -->|"documents"| node_n10
node_n18 -->|"documents"| node_n11
node_n18 -->|"documents"| node_n16
node_n19 -->|"probes"| node_n5
node_n19 -->|"probes"| node_n10
node_n20 -->|"verifies"| node_n5
node_n20 -->|"verifies"| node_n10
node_n20 -->|"verifies"| node_n11
node_n20 -->|"verifies"| node_n12
node_n20 -->|"verifies"| node_n13
node_n20 -->|"verifies"| node_n15
node_n21 -->|"packages"| node_n1
node_n21 -->|"publishes"| node_n18

click node_n1 "https://github.com/negu93/cvnn/blob/master/cvnn/__init__.py"
click node_n2 "https://github.com/negu93/cvnn/blob/master/cvnn/cli.py"
click node_n3 "https://github.com/negu93/cvnn/blob/master/cvnn/__main__.py"
click node_n4 "https://github.com/negu93/cvnn/blob/master/cvnn/_version.py"
click node_n5 "https://github.com/negu93/cvnn/tree/master/cvnn/layers"
click node_n6 "https://github.com/negu93/cvnn/blob/master/cvnn/layers/core.py"
click node_n7 "https://github.com/negu93/cvnn/blob/master/cvnn/layers/convolutional.py"
click node_n8 "https://github.com/negu93/cvnn/blob/master/cvnn/layers/pooling.py"
click node_n9 "https://github.com/negu93/cvnn/blob/master/cvnn/layers/upsampling.py"
click node_n10 "https://github.com/negu93/cvnn/blob/master/cvnn/activations.py"
click node_n11 "https://github.com/negu93/cvnn/blob/master/cvnn/initializers.py"
click node_n12 "https://github.com/negu93/cvnn/blob/master/cvnn/losses.py"
click node_n13 "https://github.com/negu93/cvnn/blob/master/cvnn/metrics.py"
click node_n14 "https://github.com/negu93/cvnn/blob/master/cvnn/tb.py"
click node_n15 "https://github.com/negu93/cvnn/blob/master/cvnn/utils.py"
click node_n16 "https://github.com/negu93/cvnn/blob/master/cvnn/real_equiv_tools.py"
click node_n17 "https://github.com/negu93/cvnn/tree/master/examples"
click node_n18 "https://github.com/negu93/cvnn/tree/master/docs"
click node_n19 "https://github.com/negu93/cvnn/tree/master/debug"
click node_n20 "https://github.com/negu93/cvnn/tree/master/tests"
click node_n21 "https://github.com/negu93/cvnn/blob/master/setup.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_n1,node_n2,node_n3,node_n4 toneBlue
class node_n5,node_n6,node_n7,node_n8,node_n9,node_n10,node_n11,node_n12,node_n13,node_n14,node_n15,node_n16 toneAmber
class node_n17,node_n18,node_n19 toneMint
class node_n20,node_n21 toneRose
```

## Components

### Package API

Public Python package entrypoints and versioning

- [cvnn API](https://github.com/negu93/cvnn/blob/master/cvnn/__init__.py): package api · Top-level package exports · `cvnn/__init__.py`
- [CLI](https://github.com/negu93/cvnn/blob/master/cvnn/cli.py): entrypoint · Command-line interface · `cvnn/cli.py`
- [Main entry](https://github.com/negu93/cvnn/blob/master/cvnn/__main__.py): module entry · Python -m entrypoint · `cvnn/__main__.py`
- [Versioning](https://github.com/negu93/cvnn/blob/master/cvnn/_version.py): release metadata · Automated version source · `cvnn/_version.py`

### Model Core

Complex-valued TensorFlow/Keras extensions

- [Layers](https://github.com/negu93/cvnn/tree/master/cvnn/layers): complex layers · Core complex-valued layer family · `cvnn/layers`
- [Dense & input](https://github.com/negu93/cvnn/blob/master/cvnn/layers/core.py): layer submodule · Core dense-style building blocks · `cvnn/layers/core.py`
- [Convolutions](https://github.com/negu93/cvnn/blob/master/cvnn/layers/convolutional.py): layer submodule · Complex conv and transpose conv · `cvnn/layers/convolutional.py`
- [Pooling](https://github.com/negu93/cvnn/blob/master/cvnn/layers/pooling.py): layer submodule · Complex pooling and unpooling · `cvnn/layers/pooling.py`
- [Upsampling](https://github.com/negu93/cvnn/blob/master/cvnn/layers/upsampling.py): layer submodule · Complex upsampling layers · `cvnn/layers/upsampling.py`
- [Activations](https://github.com/negu93/cvnn/blob/master/cvnn/activations.py): complex activations · Hidden and output activation transforms · `cvnn/activations.py`
- [Initializers](https://github.com/negu93/cvnn/blob/master/cvnn/initializers.py): weight init · Complex-aware parameter initialization · `cvnn/initializers.py`
- [Losses](https://github.com/negu93/cvnn/blob/master/cvnn/losses.py): training objective · Loss functions for training · `cvnn/losses.py`
- [Metrics](https://github.com/negu93/cvnn/blob/master/cvnn/metrics.py): training metrics · Evaluation metrics · `cvnn/metrics.py`
- [TensorBoard](https://github.com/negu93/cvnn/blob/master/cvnn/tb.py): training observability · Training visualization helpers · `cvnn/tb.py`
- [Utils](https://github.com/negu93/cvnn/blob/master/cvnn/utils.py): support utilities · Data and model helpers · `cvnn/utils.py`
- [Real equivalence](https://github.com/negu93/cvnn/blob/master/cvnn/real_equiv_tools.py): analysis tools · Complex-vs-real comparison helpers · `cvnn/real_equiv_tools.py`

### Research & Docs

Examples, analysis artifacts, and documentation

- [Examples](https://github.com/negu93/cvnn/tree/master/examples): usage demos · End-user model scripts and notebooks · `examples`
- [Docs](https://github.com/negu93/cvnn/tree/master/docs): sphinx docs · Rendered documentation and analysis artifacts · `docs`
- [Debug notebooks](https://github.com/negu93/cvnn/tree/master/debug): ad hoc experiments · Investigation scripts and notebooks · `debug`

### Validation & Release

Tests and packaging/release scaffolding

- [Tests](https://github.com/negu93/cvnn/tree/master/tests): api contract tests · Coverage across layers, activations, losses, metrics, dtype, and API behavior · `tests`
- [Packaging](https://github.com/negu93/cvnn/blob/master/setup.py): distribution config · Build and packaging files · `setup.py`

## Connections

- cvnn API → Layers: exposes · Package API re-exports the core layer surface
- cvnn API → Activations: exposes · Package API surfaces activation helpers
- cvnn API → Initializers: exposes · Package API surfaces initializers
- cvnn API → Losses: exposes · Package API surfaces losses
- cvnn API → Metrics: exposes · Package API surfaces metrics
- CLI → cvnn API: uses · CLI enters through the package API
- Main entry → CLI: launches · Module execution routes to CLI
- Versioning → Packaging: feeds · Version metadata supports packaging and release
- Layers → Dense & input: contains · Layer package groups core dense/input layers
- Layers → Convolutions: contains · Layer package groups convolutional layers
- Layers → Pooling: contains · Layer package groups pooling layers
- Layers → Upsampling: contains · Layer package groups upsampling layers
- Dense & input → Initializers: depends on · Layers use complex-aware initializers
- Dense & input → Activations: uses · Layer outputs flow through activations
- Convolutions → Initializers: depends on · Convolution kernels require initialization
- Pooling → Activations: uses · Pooling blocks connect to output transforms when needed
- Upsampling → Activations: uses · Upsampling participates in activation-driven models
- Activations → Losses: feeds · Final activations produce real-valued outputs for loss computation
- Activations → Metrics: feeds · Activations also shape metric inputs
- Utils → Real equivalence: supports · General utilities back real-equivalence analysis
- Real equivalence → Docs: documents · Comparison tools are described in the docs
- Examples → Layers: builds with · Examples construct models from complex layers
- Examples → Activations: configures · Examples demonstrate activation choices and real outputs
- Examples → Losses: trains with · Examples rely on standard Keras training objectives
- Docs → Layers: documents · Docs explain the layer subsystem
- Docs → Activations: documents · Docs cover activation families and output transforms
- Docs → Initializers: documents · Docs cover initializer variants
- Docs → Real equivalence: documents · Docs include Monte Carlo and real-vs-complex analysis
- Debug notebooks → Layers: probes · Debug work explores layer behavior and stability
- Debug notebooks → Activations: probes · Debug work explores activation and gradient behavior
- Tests → Layers: verifies · Tests assert layer contracts
- Tests → Activations: verifies · Tests assert activation behavior
- Tests → Initializers: verifies · Tests check initialization rules
- Tests → Losses: verifies · Tests check losses
- Tests → Metrics: verifies · Tests check metrics
- Tests → Utils: verifies · Tests cover utilities and conversions
- Packaging → cvnn API: packages · Build configuration distributes the library
- Packaging → Docs: publishes · Packaging includes documentation artifacts