diff --git a/AGENT_OVERVIEW.md b/AGENT_OVERVIEW.md new file mode 100644 index 0000000..485e214 --- /dev/null +++ b/AGENT_OVERVIEW.md @@ -0,0 +1,344 @@ +# 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/`. diff --git a/Functions/Channel_structures/awgn_channel.m b/Functions/Channel_structures/awgn_channel.m new file mode 100644 index 0000000..6cf5580 --- /dev/null +++ b/Functions/Channel_structures/awgn_channel.m @@ -0,0 +1,5 @@ +function signal_out = awgn_channel(signal_in) + + signal_out = signal_in; + +end \ No newline at end of file