Infos für Overlord II
This commit is contained in:
Silas Oettinghaus
344
AGENT_OVERVIEW.md
Normal file
344
AGENT_OVERVIEW.md
Normal file
@@ -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/`.
|
||||
Reference in New Issue
Block a user