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