imdd_silas/AGENT_OVERVIEW.md

# IM/DD Simulation Framework Overview

This file is for agents that encounter this repository for the first time.
Its goal is to explain what the codebase is for, where the main building
blocks live, and how a typical IM/DD workflow is assembled.

It is not a testing guide. The focus here is the simulation framework itself.

## What This Repository Is

This repository is a MATLAB-based simulation and analysis framework for
IM/DD optical communication systems.

At a high level, the codebase supports:

- generation of digital symbol and bit streams
- electrical transmitter modeling
- electro-optical modulation
- optical channel modeling
- photodetection and receiver front-end processing
- digital signal processing and sequence detection
- metric evaluation such as BER, GMI, AIR, EVM, and SNR
- project-specific simulation scripts and experimental analysis workflows

The codebase is not just one monolithic simulator. It is a toolkit of
reusable classes plus many project scripts that assemble those classes in
different ways.

## Mental Model

The easiest way to understand the repository is as a staged signal chain:

1. Information signal generation
2. Symbol mapping and pulse shaping
3. AWG / electrical drive path
4. Optical modulation
5. Fiber / channel propagation
6. Receiver front-end
7. Synchronization and DSP
8. Performance evaluation

The classes in `Classes/` implement the reusable blocks.
The scripts in `projects/` wire those blocks together into concrete systems.

## Suggested First File To Read

For a compact end-to-end example, start here:

- `projects/IMDD_base_system/minimal_example.m`

That file shows a reduced but representative full workflow:

- `PAMsource`
- `AWG`
- `EML`
- `Fiber`
- `Amplifier`
- `Photodiode`
- `Filter`
- `Scope`
- matched filtering
- synchronization
- equalization / MLSE

If you need to understand “how the system is intended to be used”, this is
one of the best entry points.

## Top-Level Structure

### `Classes/`

This is the core reusable framework.
Most simulation building blocks live here.

Subfolders are organized by role:

- `00_signals`
  Base signal classes and core signal behavior.
  This is the semantic foundation used by most of the rest of the codebase.

- `01_transmit`
  Digital TX-side blocks such as bit/symbol generation, mapping, pulse
  shaping, and AWG-related functionality.

- `02_etc`
  General-purpose support blocks, especially filtering and amplification.

- `02_optical`
  Optical-domain components such as modulators, multiplexing, fiber/channel
  propagation, and related physical effects.

- `03_electrical`
  Electrical-domain helper blocks and traces.

- `03_receive`
  RX-side front-end blocks such as photodiodes and scopes/ADC behavior.

- `04_DSP`
  Equalizers, timing recovery, postfilters, coding blocks, and sequence
  detection such as MLSE.

- `05_Lab`
  Instrument-control classes for real hardware.
  These are not just simulations. They can talk to reachable devices.

- `DataBaseHandler`
  Query/filter/result structures and database-facing helper classes.

- `Warehouse_class`
  More specialized storage / plotting / result-handling infrastructure.

### `Functions/`

This holds free functions and workflow helpers that are not packaged as
classes.

Important subareas:

- `EQ_structures`
  Higher-level DSP driver functions such as `ffe`, `vnle_postfilter_mlse`,
  and related end-stage evaluation helpers.

- `Metrics`
  BER, EVM, GMI, AIR, SNR, and related performance calculations.

- `EQ_visuals`
  Diagnostic and visualization helpers for equalizers and result analysis.

- `channel_structures`
  Channel-model helpers.

- `Job_Processing`
  Scriptable processing helpers for bigger job/result workflows.

- `Theory`
  Supporting theory calculations and one-off analytic utilities.

### `Datatypes/`

This contains enums and small type definitions used throughout the codebase.

Examples:

- normalization modes
- power notation
- filter types
- modulation / adaptation enums

When a class constructor takes a symbolic mode value, it is often defined here.

### `projects/`

This is where the reusable framework gets turned into concrete systems,
experiments, and studies.

The `projects/` folder is broad and includes:

- minimal examples
- paper-specific studies
- lab analysis scripts
- offline DSP pipelines
- experiment-specific workflows

These scripts are often the best place to understand intended usage patterns.

### `Tests/`

This contains the current MATLAB unit/integration test framework.
It validates parts of the reusable framework, not the full meaning of the
repository.

Use it as a quality tool, not as the primary documentation source for what
the simulation does.

## Core Signal Classes

The repository uses class-based signal objects instead of raw arrays whenever
possible.

Key signal classes:

- `Signal`
  Base class with common signal behavior, metadata, logbook, arithmetic,
  normalization, resampling, plotting, and utility methods.

- `Informationsignal`
  Discrete/digital information-level representation.

- `Electricalsignal`
  Electrical-domain signal representation.

- `Opticalsignal`
  Optical-domain signal representation including optical metadata such as
  wavelength and ASE-related quantities.

These classes are central because many other blocks accept or return them.

## Typical Workflow Composition

A representative IM/DD chain often looks like this:

1. `PAMsource`
   Creates bits, mapped symbols, and shaped digital transmit signals.

2. `AWG`
   Applies DAC-like processing, upsampling, quantization, and optional
   filtering.

3. `EML`
   Converts the electrical drive signal to an optical signal.

4. `Fiber`
   Applies optical channel propagation.

5. `Amplifier`
   Sets optical power / gain and can manipulate ASE handling.

6. `Photodiode`
   Performs square-law detection and creates an electrical RX signal.

7. `Filter`
   Applies electrical filtering.

8. `Scope`
   Models ADC / sampling / quantization / optional RX-side LPF behavior.

9. `Pulseformer` in matched-filter mode
   Used again on the RX side as matched filtering.

10. `tsynch`
   Synchronizes the RX signal against transmitted symbols.

11. DSP blocks
   Examples:
   - `FFE`
   - `EQ`
   - `Postfilter`
   - `MLSE`
   - timing-recovery variants

12. Metrics
   Performance is evaluated via helper functions and result structures.

## Two Important Layers

There are two distinct abstraction levels in the repo:

### 1. Block-level classes

Examples:

- `PAMsource`
- `Pulseformer`
- `AWG`
- `EML`
- `Fiber`
- `Photodiode`
- `Scope`
- `FFE`
- `MLSE`

These are the reusable simulation primitives.

### 2. Workflow-level functions/scripts

Examples:

- `projects/.../minimal_example.m`
- `Functions/EQ_structures/ffe.m`
- `Functions/EQ_structures/vnle_postfilter_mlse.m`

These assemble the primitives into practical runs and performance outputs.

When debugging behavior, it matters which layer you are in:

- if a signal object has the wrong shape or `fs`, look at block-level classes
- if BER/GMI pipelines behave unexpectedly, also inspect workflow-level DSP helpers

## Where To Look For What

If you want to understand:

- base signal semantics:
  read `Classes/00_signals/*`

- transmitter generation:
  read `Classes/01_transmit/*`

- optical propagation:
  read `Classes/02_optical/*`

- receiver modeling:
  read `Classes/03_receive/*`

- equalization and detection:
  read `Classes/04_DSP/*` and `Functions/EQ_structures/*`

- metric definitions:
  read `Functions/Metrics/*`

- intended end-to-end usage:
  read `projects/IMDD_base_system/minimal_example.m`

## How To Approach The Repo As A New Agent

A good first-pass reading order is:

1. `projects/IMDD_base_system/minimal_example.m`
2. `Classes/00_signals/Signal.m`
3. `Classes/01_transmit/PAMsource.m`
4. `Classes/01_transmit/Pulseformer.m`
5. `Classes/01_transmit/AWG.m`
6. `Classes/02_optical/EML.m`
7. `Classes/02_optical/Fiber.m`
8. `Classes/03_receive/Photodiode.m`
9. `Classes/03_receive/Scope.m`
10. `Functions/EQ_structures/ffe.m`
11. `Functions/EQ_structures/vnle_postfilter_mlse.m`
12. `Classes/04_DSP/Equalizer/FFE.m`
13. `Classes/04_DSP/Sequence Detection/MLSE.m`

This gives both the architectural view and the runtime path.

## Practical Safety Note

Do not casually execute or test `Classes/05_Lab/*`.

Those are lab-device control classes, not harmless simulations.
In this environment, reachable device IPs can exist, and executing those
classes may change instrument set points and interfere with active experiments.

Treat `05_Lab` as operational code, not as a normal simulation subfolder.

## Final Summary

The repository is best understood as:

- a reusable class library for IM/DD system building blocks
- plus workflow helpers for DSP and analysis
- plus many project scripts that instantiate those blocks for concrete studies

If you are lost, do not start from `Tests/`.
Start from the minimal project workflow, then map each stage back to the
relevant class folder in `Classes/`.