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/`.
|
||||||
5
Functions/Channel_structures/awgn_channel.m
Normal file
5
Functions/Channel_structures/awgn_channel.m
Normal file
@@ -0,0 +1,5 @@
|
|||||||
|
function signal_out = awgn_channel(signal_in)
|
||||||
|
|
||||||
|
signal_out = signal_in;
|
||||||
|
|
||||||
|
end
|
||||||
Reference in New Issue
Block a user