Adds Zenodo badge to README (#10)

* Adds Zenodo badge to README

* Adds CITATION.cff including author names

* Updates command line parser.

* Adds program descriptions to command line help in simulator programs

CITATION.cff

@@ -0,0 +1,13 @@
+cff-version: 1.2.0
+message: "If you use this software, please cite it as below."
+title: "LDPC4QKD: LDPC Codes for Rate Adaptive Distributed Source Coding"
+doi: 10.5281/zenodo.5579246
+publisher: Zenodo
+url: https://doi.org/10.5281/zenodo.5579246
+authors:
+  - family-names: Baliuka
+    given-names: Adomas
+    orcid: "https://orcid.org/0000-0002-7064-8502"
+  - family-names: Dupraz
+    given-names: Elsa
+license: MIT

README.md

@@ -1,6 +1,7 @@
 [![workflow](https://github.com/XQP-Munich/LDPC4QKD/actions/workflows/ci-cmake_tests.yml/badge.svg)](https://github.com/XQP-Munich/LDPC4QKD/actions)
 [![codecov](https://codecov.io/gh/XQP-Munich/LDPC4QKD/branch/main/graph/badge.svg?token=GV9453ZM42)](https://codecov.io/gh/XQP-Munich/LDPC4QKD)
 [![License](https://img.shields.io/github/license/XQP-Munich/LDPC4QKD)](./LICENSE)
+[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.5579246.svg)](https://doi.org/10.5281/zenodo.5579246)
 # LDPC4QKD: LDPC codes for rate adaptive distributed source coding 
 
 Note: This repository is still missing some documentation, which will be added very soon.

benchmarks/CmdParser-1.1.0/cmdparser.hpp → benchmarks/CmdParser-91aaa61e/cmdparser.hpp

@@ -291,6 +291,24 @@ namespace cli {
 			enable_help();
 		}
 
+		Parser(int argc, const char** argv, std::string generalProgramDescriptionForHelpText) :
+				_appname(argv[0]),
+				_general_help_text(std::move(generalProgramDescriptionForHelpText)) {
+			for (int i = 1; i < argc; ++i) {
+				_arguments.push_back(argv[i]);
+			}
+			enable_help();
+		}
+
+		Parser(int argc, char** argv, std::string generalProgramDescriptionForHelpText) :
+				_appname(argv[0]),
+				_general_help_text(std::move(generalProgramDescriptionForHelpText)) {
+			for (int i = 1; i < argc; ++i) {
+				_arguments.push_back(argv[i]);
+			}
+			enable_help();
+		}
+
 		~Parser() {
 			for (size_t i = 0, n = _commands.size(); i < n; ++i) {
 				delete _commands[i];
@@ -507,6 +525,7 @@ namespace cli {
 
 		std::string usage() const {
 			std::stringstream ss { };
+			ss << _general_help_text << "\n\n";
 			ss << "Available parameters:\n\n";
 
 			for (const auto& command : _commands) {
@@ -558,8 +577,16 @@ namespace cli {
 			return ss.str();
 		}
 
+		const std::string &get_general_help_text() const {
+			return _general_help_text;
+		}
+
+		void set_general_help_text(const std::string &generalHelpText) {
+			_general_help_text = generalHelpText;
+		}
 	private:
 		const std::string _appname;
+		std::string _general_help_text;
 		std::vector<std::string> _arguments;
 		std::vector<CmdBase*> _commands;
 	};

benchmarks/main_rate_adapted_fer.cpp

@@ -1,17 +1,23 @@
 //
 // Created by alice on 09.06.21.
-// Simulation script to determine frame error rate (FER) uppon belief propagation (BP) decoding of an LDPC code.
-// The LDPC code may be rate adapted before the simulation.
-// For more information on simulation settings, see the command line help.
+// Note: Names and meaning of command line parameters are defined below.
 //
+constexpr auto help_text =
+        "Frame Error Rate (FER) Simulator for Rate Adapted LDPC Codes\n"
+        "\n"
+        "This software is used to \n"
+        "- load an LDPC code (from a .cscmat file storing the full binary LDPC matrix in compressed sparse column (CSC) format, no QC exponents allowed!)\n"
+        "- load rate adaption (from a csv file, list of pairs of row indices combined at each rate adaption step) "
+        "(this is optional; without rate adatpion only FER of the LDPC code can be simulated)\n"
+        "- Simulate the FER of the given LDPC code at specified amount of rate adaption.";
 
 // Standard library
 #include <iostream>
 #include <random>
 #include <chrono>
 
 // Command line argument parser library
-#include "CmdParser-1.1.0/cmdparser.hpp"
+#include "CmdParser-91aaa61e/cmdparser.hpp"
 
 // Project scope
 #include "rate_adaptive_code.hpp"
@@ -121,7 +127,7 @@ void configure_parser(cli::Parser &parser) {
 
 int main(int argc, char *argv[]) {
     // parse command line arguments
-    cli::Parser parser(argc, argv);
+    cli::Parser parser(argc, argv, help_text);
     configure_parser(parser);
     parser.run_and_exit_if_error();
 

benchmarks/main_rate_adapted_simulation.cpp

@@ -1,17 +1,19 @@
 //
 // Created by alice on 07.09.21.
-// In a Slepian-Wolf coding setting, for a given codeword and noised codeword, there is a minimum coding rate at which
-// the syndrome decoding succeeds. This program determines the average minimum coding rate across many noised codewords.
 //
-
+constexpr auto help_text =
+        "Slepian-Wolf Critical Code Rate Simulator for Rate Adapted LDPC Codes\n"
+        "\n"
+        "In a Slepian-Wolf coding setting, for a given codeword and noised codeword, there is a minimum coding rate at which the syndrome decoding succeeds.\n"
+        "This program determines the average minimum coding rate across many noised codewords.";
 
 // Standard library
 #include <iostream>
 #include <random>
 #include <chrono>
 
 // Command line argument parser library
-#include "CmdParser-1.1.0/cmdparser.hpp"
+#include "CmdParser-91aaa61e/cmdparser.hpp"
 
 // Project scope
 #include "rate_adaptive_code.hpp"
@@ -34,13 +36,12 @@ std::vector<std::size_t> run_simulation(RateAdaptiveCodeTemplate &H,
 
     std::size_t frame_idx{0};  // counts the number of iterations
     for (; frame_idx < num_frames_to_test; ++frame_idx) {
-        std::size_t success_syndrome_size = H.getNCols(); // assume whole codeword leaked unless decoding success
 
         std::size_t min_syndrome_size = H.get_n_rows_mother_matrix() - H.get_max_ra_steps();;
         std::size_t max_syndrome_size = H.get_n_rows_mother_matrix();
         // bisection
         while ((max_syndrome_size - min_syndrome_size) > ra_step_accuracy) {
-                        std::vector<bool> x(H.getNCols()); // true data sent over a noisy channel
+            std::vector<bool> x(H.getNCols()); // true data sent over a noisy channel
             noise_bitstring_inplace(rng, x, 0.5);  // choose it randomly.
 
             std::vector<bool> syndrome;  // syndrome for error correction, which is sent over a noise-less channel.
@@ -117,7 +118,7 @@ void configure_parser(cli::Parser &parser) {
 
 int main(int argc, char *argv[]) {
     // parse command line arguments
-    cli::Parser parser(argc, argv);
+    cli::Parser parser(argc, argv, help_text);
     configure_parser(parser);
     parser.run_and_exit_if_error();
 
@@ -160,7 +161,8 @@ int main(int argc, char *argv[]) {
     std::cout << "\n\n";
 
     double avg_synd_size = avg(syndrome_size_success);
-    std::cout << "Average syndrome size (out of " << num_frames_to_test << " codewords tried): " << avg_synd_size << std::endl;
+    std::cout << "Average syndrome size (out of " << num_frames_to_test << " codewords tried): " << avg_synd_size
+              << std::endl;
 
     double avg_rate = avg_synd_size / static_cast<double>(H.getNCols());
     std::cout << "Average rate: " << avg_rate << " (inefficiency f = " << avg_rate / h2(p) << ")" << std::endl;