From f3c9cfc01ea57ed62e45115287a2c7dfc1f4e9fb Mon Sep 17 00:00:00 2001
From: Craig Warren <craig.warren@northumbria.ac.uk>
Date: Sat, 19 Nov 2022 20:31:42 +0000
Subject: [PATCH] Added return (currently unused) from main gprMax call

---
 gprMax/contexts.py | 18 ++++++++++++++++--
 gprMax/gprMax.py   | 27 +++++++++++++++++----------
 2 files changed, 33 insertions(+), 12 deletions(-)

diff --git a/gprMax/contexts.py b/gprMax/contexts.py
index c05f7167..3fd4ab0f 100644
--- a/gprMax/contexts.py
+++ b/gprMax/contexts.py
@@ -45,7 +45,13 @@ class Context:
         self.tsimstart = None        
 
     def run(self):
-        """Run the simulation in the correct context."""
+        """Run the simulation in the correct context.
+        
+        Returns:
+            results: dict that can contain useful results/data from simulation.
+        """
+
+        results = {}
         self.tsimstart = timer()
         self.print_logo_copyright()
         print_host_info(config.sim_config.hostinfo)
@@ -80,6 +86,8 @@ class Context:
         self.tsimend = timer()
         self.print_time_report()
 
+        return results
+
     def print_logo_copyright(self):
         """Prints gprMax logo, version, and copyright/licencing information."""
         logo_copyright = logo(__version__ + ' (' + codename + ')')
@@ -134,7 +142,12 @@ class MPIContext(Context):
             model.solve(solver)
 
     def run(self):
-        """Specialise how the models are run."""
+        """Specialise how the models are run.
+        
+        Returns:
+            results: dict that can contain useful results/data from simulation.
+        """
+
         if self.rank == 0:
             self.tsimstart = timer()
             self.print_logo_copyright()
@@ -173,3 +186,4 @@ class MPIContext(Context):
         if executor.is_master():
             self.tsimend = timer()
             self.print_time_report()
+            return results
diff --git a/gprMax/gprMax.py b/gprMax/gprMax.py
index 6e11e785..e57650de 100644
--- a/gprMax/gprMax.py
+++ b/gprMax/gprMax.py
@@ -96,9 +96,8 @@ def run(scenes=args_defaults['scenes'],
         write_processed=args_defaults['write_processed'],
         log_level=args_defaults['log_level'],
         log_file=args_defaults['log_file']):
-    """This is the main function for gprMax when entering using application
-        programming interface (API). Run the simulation for the given list of 
-        scenes.     
+    """Entry point for application programming interface (API). Runs the 
+        simulation for the given list of scenes.     
     """
 
     args = argparse.Namespace(**{'scenes': scenes,
@@ -121,9 +120,7 @@ def run(scenes=args_defaults['scenes'],
 
 
 def cli():
-    """Main function for gprMax when entering using the command line interface 
-        (CLI).
-    """
+    """Entry point for command line interface (CLI)."""
 
     # Parse command line arguments
     parser = argparse.ArgumentParser(prog='gprMax', 
@@ -154,16 +151,24 @@ def cli():
                         help=help_msg['log_file'])
     args = parser.parse_args()
 
-    run_main(args)
+    results = run_main(args)
+
+    return results
 
 
 def run_main(args):
-    """Called by either run (API) or main (CLI).
+    """Runs simulation contexts. Called by either API or CLI.
 
     Args:
         args: namespace with arguments from either API or CLI.
+
+    Returns:
+        results: dict that can contain useful results/data from simulation. 
+                    Enables these to be propagated to calling script.
     """
 
+    results = {}
+
     logging_config(level=args.log_level, log_file=args.log_file)
 
     config.sim_config = config.SimulationConfig(args)
@@ -171,8 +176,10 @@ def run_main(args):
     # MPI running with (OpenMP/CUDA/OpenCL)
     if config.sim_config.args.mpi:
         context = MPIContext()
-        context.run()
+        results = context.run()
     # Standard running (OpenMP/CUDA/OpenCL)
     else:
         context = Context()
-        context.run()
+        results = context.run()
+
+    return results
\ No newline at end of file