Member Avatar for vancasas

how do you document simulation of algorithms ?

  • 6 Contributors
  • 7 Replies
  • 139 Views
  • 1 Day Discussion Span
  • Latest Post Latest Post by Sutanu

Dani AI

Generated

A short, practical approach to documenting an algorithm simulation so it stays useful and reproducible years later. asked the original question and several good starting points were raised by others: inline comments (@vegeseat), diagrams () and automated/doc-extractor approaches (comments and generators noted by , and ). Use those ideas, but also capture the experiment recipe, validation, and measurement method so someone can reproduce results exactly.

Essential items to include:

  • Purpose and hypothesis: what the simulation is intended to show.
  • Algorithm description and concise pseudocode (one clear trace example).
  • Theoretical expectations: complexity and any bounds to compare against.
  • Exact environment: OS, CPU, compiler and flags, library versions.
  • Inputs and generators: formats, seeds, example small inputs.
  • Reproducibility recipe: exact build/run commands and config files.
  • Measurement method: timers used, warmup, repeat count, aggregation (median/IQR).
  • Validation tests: unit checks, invariants, correctness for edge cases.
  • Output format and sample results (CSV column descriptions).
  • Known limitations, assumptions, and a short changelog.

Practical measurement and troubleshooting tips: always use release/optimized builds for timing; pin or describe CPU power settings; run many repetitions and discard first-run warmup; log random seeds and full command lines; include checksums of inputs and small-case golden outputs to confirm correctness. If results vary unexpectedly, compare compiler flags, deterministic inputs/seeds, and run on identical hardware or record virtualization differences.

Example minimal run recipe and README skeleton to include with the project:

# reproducibility example
./run_sim --algo X --input inputs/size1000.json --seed 42 --reps 50 --out results/size1000.csv
README.md:
- Overview / Goal
- Algorithm + pseudocode + trace
- Build & exact run commands
- Inputs & seeds
- Experiments (params, reps)
- Results files + plots
- Validation tests
- Known issues / changelog

Combine inline comments, diagrams and a documented recipe so others can verify both correctness and performance without guessing.

Recommended Answers

All 7 Replies

Member Avatar for vegaseat

Write your code and use plenty of remarks.

Member Avatar for proghelper

Can use a flow chart I guess

---------------------------

Member Avatar for vegaseat

C# can create an XML document file using certain remark notations. I am not sure if any C++ compilers have that capability? Darn, I hate to be oblivious!

Member Avatar for Ancient Dragon

you can use javadoc notations in any program file written in any computer language. Not sure what program reads them and creates the html file. I had to make javadoc comments in my programs about a month or so ago, but I did not have to create the html files.

Member Avatar for Sutanu

There is a tool 'oxygen' which generates the document from your C++ code. Provided you have sufficient remarks in it

Member Avatar for Sutanu

Yeah you are right. I'm sorry, it should be Doxygen and not oxygen.

Be a part of the DaniWeb community

We're a friendly, industry-focused community of developers, IT pros, digital marketers, and technology enthusiasts meeting, networking, learning, and sharing knowledge.