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/.