Simrunner Doku Comments added

simrunner/simrunner.py

@@ -4,7 +4,13 @@ import subprocess
 import argparse
 import getpass
 
+# List of byte sizes for the events
+BYTE_SIZES = ['16', '32', '64', '128', '256', '512', '1024', '2048', '4096', '8192',
+              '16384', '32768', '65536', '131072', '262144', '524288', '1048576', '2097152',
+              '4194304', '8388608']
 
+
+# Function to parse command-line arguments
 def parse_arguments():
     main_directory = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
     default_sim_path = os.path.join(os.path.dirname(__file__), "../build/src/detsim")
@@ -25,6 +31,7 @@ def parse_arguments():
     return parser.parse_args()
 
 
+# Function to read the configuration from a JSON file
 def read_config():
     config_path = os.path.join(os.path.dirname(os.path.abspath(__file__)), 'data_config.json')
     with open(config_path, "r") as file:
@@ -32,16 +39,15 @@ def read_config():
     return d_config
 
 
+# Function to set arguments for various data configurations
 def set_arguments_various(da_config):
     data_config = da_config
     e_list = []
-    byte_sizes = ['16', '32', '64', '128', '256', '512', '1024', '2048', '4096', '8192',
-                  '16384', '32768', '65536', '131072', '262144', '524288', '1048576', '2097152',
-                  '4194304', '8388608']
-
-    for event in byte_sizes:
+    # Loop through each byte size to create corresponding event arguments
+    for event in BYTE_SIZES:
         event_name = "Data_Set_" + event
         arguments = ["-s", event]
+        # Loop through the data configuration and append key-value pairs as arguments
         for outer_key in data_config.keys():
             if outer_key == 'data_config_various':
                 inner_dict = data_config[outer_key]
@@ -53,14 +59,17 @@ def set_arguments_various(da_config):
                 arguments.append('-o')
                 arguments.append(event_name)
                 e_list.append(arguments)
+    # Return the list of event arguments for various byte sizes
     return e_list
 
 
+# Function to set arguments for long data configurations
 def set_arguments_long(da_config):
     data_config = da_config
     e_list = []
     event_name = "Data_Set_Long"
     arguments = []
+    # Loop through the data configuration and append key-value pairs as arguments
     for outer_key in data_config.keys():
         if outer_key == 'data_config_long':
             inner_dict = data_config[outer_key]
@@ -72,20 +81,26 @@ def set_arguments_long(da_config):
             arguments.append('-o')
             arguments.append(event_name)
             e_list.append(arguments)
+    # Return the list of event arguments for long data configuration
     return e_list
 
 
+# Function to create the list of event arguments based on the chosen function
 def create_event_list():
     if args.function == 'long':
         e_list = set_arguments_long(read_config())
     else:
         e_list = set_arguments_various(read_config())
+    # Return the final list of event arguments
     return e_list
 
 
+# Function to run the detector simulation with the given event arguments
 def run_sim(e_list, d_path, sim_path, main_path):
+    # Create the 'output/statistics' directory if it doesn't exist
     stat_path = os.path.join(main_path, "output/statistics")
     os.makedirs(stat_path, mode=0o777, exist_ok=True)
+    # Loop through each event and run the detector simulation
     for event in e_list:
         folder_name = event[-1]
         stat_file_name = "statistics_" + folder_name
@@ -94,32 +109,41 @@ def run_sim(e_list, d_path, sim_path, main_path):
             # Remote execution on multiple machines with specified user
             for host in args.hosts:
                 ssh_target = f'{args.user}@{host}'
+                # Create remote output folders and update the event path accordingly
                 remote_output = make_folders_remote(test_data_path, output_path, ssh_target, host)
                 event[-1] = remote_output
+                # Construct the command to run the simulation on the remote machine via SSH
                 command = ["ssh", ssh_target, sim_path] + event
                 result = subprocess.run(command, capture_output=True, text=True)
                 output = result.stdout
                 errors = result.stderr
+                # Print the simulation output and errors, along with the return code if there is any error
                 terminal_output(output, errors, result.returncode)
+                # Write the simulation output to a statistics file
                 relativ_path_stat = os.path.join(stat_path, stat_file_name + f"_{host}.dat")
                 with open(relativ_path_stat, "w") as stat_file:
                     stat_file.write(output)
                 print(f"{folder_name}_{host} done!")
         # Local execution
         else:
+            # Create local output folders and update the event path accordingly
             make_folders_lokal(test_data_path, output_path)
             event[-1] = output_path
+            # Construct the command to run the simulation locally
             command = [sim_path] + event
             result = subprocess.run(command, capture_output=True, text=True)
             output = result.stdout
             errors = result.stderr
+            # Print the simulation output and errors, along with the return code if there is any error
             terminal_output(output, errors, result.returncode)
+            # Write the simulation output to a statistics file
             relativ_path_stat = os.path.join(stat_path, stat_file_name + ".dat")
             with open(relativ_path_stat, "w") as stat_file:
                 stat_file.write(output)
             print(f"{folder_name} done!")
 
 
+# Function to print terminal output and handle errors
 def terminal_output(output, errors, return_code):
     print(output)
     print(errors)
@@ -127,11 +151,13 @@ def terminal_output(output, errors, return_code):
         print("return code: ", return_code)
 
 
+# Function to create local folders for test data and output
 def make_folders_lokal(test_path, output_path):
     os.makedirs(test_path, mode=0o777, exist_ok=True)
     os.makedirs(output_path, mode=0o777, exist_ok=True)
 
 
+# Function to create remote folders for test data and output
 def make_folders_remote(test_path, output_path, ssh_target, host):
     host_output = output_path + f"_{host}"
     test_command = f'ssh {ssh_target} "mkdir -p {test_path}"'
@@ -141,6 +167,7 @@ def make_folders_remote(test_path, output_path, ssh_target, host):
     return host_output
 
 
+# Function to pull data from remote machines to the local machine
 def pull_data(source_path, desti_path):
     if args.hosts:
         for host in args.hosts: