Adaptive Modems

Boring Project Series, Episode 9

Adaptive Modems is a Java-based simulation suite for digital communication systems, focusing on adaptive modulation over noisy channels. It provides a framework for symbol-level Monte-Carlo simulations, empirical BER curve generation, and adaptive link evaluation. The project is designed for research, education, and benchmarking in wireless communications.

For a deeper understanding of the theory and mathematical models behind the simulations, or if you want to add new settings or extend the project, see theory.md.

Motivation & Context

Modern wireless systems dynamically select modulation schemes to optimize throughput and reliability as channel conditions change. This project models such adaptive behavior, allowing users to:

• Simulate realistic symbol-level transmission and error rates
• Evaluate adaptive selection strategies
• Generate empirical benchmarks for BER vs SNR

Features

• Symbol-level Monte-Carlo BER simulation: Supports BPSK, QPSK, 16QAM, 64QAM. Easily extensible for other modulations.
• Empirical BER lookup table (LUT): Load CSV curves for real-world or simulated BER data, enabling more accurate adaptive decisions.
• Adaptive link simulation: Models a link that selects modulation based on estimated SNR, with configurable estimator bias and noise.
• Benchmarking: Generates reproducible CSV outputs for BER curves and adaptive link results.
• Comprehensive testing: JUnit 5 tests cover all major components, including edge cases and interpolation logic.
• Extensible architecture: Add new modulation schemes or selection metrics with minimal code changes.

Requirements

• Java 25 (see pom.xml)
• Maven 3.9+

Installation & Build

Clone the repository and build with Maven:

mvn -q -DskipTests package

Compiled classes and JARs are in target/.

Running Tests

Run all unit tests:

mvn -q test

Test reports are written to target/surefire-reports/. All major features are covered by JUnit 5 tests in src/test/java/com/spidy/Modems/.

Running Simulations

Empirical BER Curve Generation

• Entry point: com.spidy.Modems.BerSimulationRunner
• Output: benchmarks/week9/ber_curves/*.csv (BPSK, QPSK, 16QAM, 64QAM)

How to Run

• In your IDE: Run the main method in BerSimulationRunner.
• Command line (with Maven exec plugin):
  1. Add the following to your pom.xml:

     <plugin>
       <groupId>org.codehaus.mojo</groupId>
       <artifactId>exec-maven-plugin</artifactId>
       <version>3.1.0</version>
     </plugin>

  2. Run:

     mvn exec:java -Dexec.mainClass="com.spidy.Modems.BerSimulationRunner"

Adaptive Link Simulation

• Simulate adaptive modulation selection using AdaptiveLinkSim.
• Configure SNR mean, SNR std, estimator bias, and estimator std.
• Results are available programmatically and via unit tests.

Example Output

Sample CSV (BER curve):

snr_db,ber
0,0.1
2,0.05
4,0.01
...

Project Layout

benchmarks/            # CSV outputs and reports generated by simulations
pom.xml                # Maven configuration (JDK 25, JUnit 5)
src/main/java/com/spidy/Modems/
  AdaptiveLinkSim.java
  BerSimulationRunner.java
  EmpiricalBERLUT.java
  Modem.java
  ModulationTable.java
  SimulationResult.java
  SimulationRow.java
  SymbolLevelSim.java
src/test/java/com/spidy/Modems/
  AdaptiveLinkSimTest.java
  EmpiricalBERLUTTest.java
  ModemTest.java
  SelectionMetricTest.java
  SymbolLevelSimTest.java

Extending the Project

• Add a new modulation: Implement its constellation and BER formula in Modem.java and update ModulationTable.java.
• Add a new selection metric: Extend selection logic in ModulationTable.java or create a new class.
• Custom empirical curves: Place CSV files in benchmarks/week9/ber_curves/ and load via EmpiricalBERLUT.
• Add or modify simulation settings: For guidance on theory, formulas, and implementation details, refer to theory.md.

Data and Results

• Benchmarks and BER curve CSV files are under benchmarks/week9/ber_curves/.
• Regenerating BER curves overwrites files in this directory.
• Output format: CSV with SNR and BER columns for each modulation scheme.

FAQ & Troubleshooting

• Q: Build fails due to JDK version?
  • A: Ensure Java 25 is installed and configured. Check pom.xml for toolchain settings.
• Q: No CSV output after running simulation?
  • A: Check file permissions and ensure the output directory exists.
• Q: How do I add a new test?
  • A: Place your test class in src/test/java/com/spidy/Modems/ and annotate with @Test.

Contributing

I welcome contributions! Please:

• Open an issue for bugs or feature requests.
• Fork the repo and submit a pull request.
• Ensure all changes are covered by unit tests.
• Follow existing code style and keep changes minimal.

License

MIT License. See LICENSE for details.