From e03b87cc0285b76a0d4143b8e40bd36b33a2c738 Mon Sep 17 00:00:00 2001
From: Dave Hadka <dhadka@github.com>
Date: Sun, 31 Dec 2023 15:50:19 -0700
Subject: [PATCH] Update Radar problem docs

---
 moeaframework.properties                      |  6 +-
 native/Radar/README.md                        | 65 ++++++++++++-------
 .../org/moeaframework/benchmarks/Radar.java   |  4 +-
 3 files changed, 51 insertions(+), 24 deletions(-)

diff --git a/moeaframework.properties b/moeaframework.properties
index 132c6e9..265ea83 100644
--- a/moeaframework.properties
+++ b/moeaframework.properties
@@ -7,6 +7,10 @@ org.moeaframework.analysis.diagnostics.problems = GAA, HBV, \
 ## 'matlab' is used, but a custom path can be specified below if required.
 #matlab.path = /usr/global/matlab/R2013a/bin/matlab
 
+## Static port used to connect to Matlab.  If unset, a port will be chosen
+## randomly.
+#matlab.port = 20001
+
 ## Time to wait, in milliseconds, after launching Matlab before attempting to
-## establish a connection.
+## establish a connection.  We found 30 seconds works well.
 #matlab.sleep = 30000
\ No newline at end of file
diff --git a/native/Radar/README.md b/native/Radar/README.md
index f0b34b8..c76b1ec 100644
--- a/native/Radar/README.md
+++ b/native/Radar/README.md
@@ -3,44 +3,65 @@
 This code is adapted from Evan J. Hughes EMO 2007 Many-Objective Radar
 Waveform Software available at http://code.evanhughes.org/.
 
-To use this problem, you must first download the ZIP from
-http://code.evanhughes.org/ and extract the file testpris.p into the
-native/Radar/bin/ folder.  This code is licensed only for academic use.  Please
-read the license terms before download and extracting this file.
+## Setup
 
-This example is designed to work with the MOEA Framework and Borg MOEA.
-For example, Borg can be used with the following command:
+The actual problem definition is not distributed in this repository since the
+code is only licensed for academic use.  To setup this problem, download the
+Radar Waveform Matlab code from http://code.evanhughes.org/ and extract
+`testpris.p` into `native/Radar/bin`.
 
-  ./borg.exe -n 10000 -v 8 -o 9 -S -D 30 -P 16801 -f out.set -- matlab
-    -nodesktop -nodisplay -nosplash -logfile out.log
-    -r "startEval(8, 9, 0, 'radar', '16801')"
+## Usage
 
-The Borg MOEA options used above include:
+Sockets are used to communicate with the Radar Waveform problem written in
+Matlab.  Consequently, this problem is only supported on POSIX-compatible systems,
+such as Linux.
 
+To optimize the problem using the Borg MOEA, run:
+
+```bash
+
+./borg.exe -n 10000 -v 8 -o 9 -S -D 30 -P 25001 -f out.set -- \
+    matlab -batch "startEval(8, 9, 0, 'radar', '25001')"
+```
+
+These options include:
+
+```
   -n 10000 - Run for 10,000 function evaluations
   -v 8     - 8 decision variables ranging from [0, 1]
   -o 9     - 9 minimization objectives
   -S       - Connect to Matlab using sockets
   -D 30    - Wait 30 seconds after launching Matlab before connecting
-  -P 16801 - Connect to port 16801
+  -P 25001 - Connect to port 25001
+```
+
+The Borg MOEA will start a new Matlab process and invoke the command:
 
-The Borg MOEA launches Matlab and runs the command
+```matlab
 
-  startEval(8, 9, 0, 'radar', '16801').
+startEval(8, 9, 0, 'radar', '25001')
+```
 
-The arguments to this command are the number of variables, number of
-objectives, number of constraints, the function name to optimize, and
-the port used for communication. 
+`startEval` reads decision variables from the socket (port 25001) and calls the Radar
+Waveform problem defined in `radar.m`.  The objectives and constraints (if any) are
+sent back to the Borg MOEA through the same socket.  The first three numbers specify the
+number of variables, objectives, and constraints, respectively.
 
-#### Troubleshooting
+## Troubleshooting
 
+```
 bind: Address already in use
 Unable to establish socket connection
-  -> Change the port number used, both in the -P option and in the startEval
-     command
+```
+
+This could indicate (1) another process is running and consuming the port;
+(2) the port hasn't been released by a previous invocation.  Consider changing
+the port number used, both in the `-P` option and in the `startEval` command.
 
+```
 execv: No such file or directory
-  -> Borg MOEA is unable to locate the matlab executable.  On Unix-like
-     systems, you may need to provide the full path to matlab.  Run
-     'which matlab' to see the full path.
+```
 
+This occurs when the Matlab executable is not found.  You might need to add
+the Matlab `bin/` folder to the system path.  Alternatively,
+set `matlab.path` in `moeaframework.properties`.
diff --git a/src/main/java/org/moeaframework/benchmarks/Radar.java b/src/main/java/org/moeaframework/benchmarks/Radar.java
index 8d13122..ed3c210 100644
--- a/src/main/java/org/moeaframework/benchmarks/Radar.java
+++ b/src/main/java/org/moeaframework/benchmarks/Radar.java
@@ -19,7 +19,9 @@ public Radar() throws Exception {
 	}
 
 	public static int startProcess() throws Exception {
-		int port = PRNG.nextInt(10000, 65536);
+		int port = Settings.PROPERTIES.getInt("matlab.port",
+				PRNG.nextInt(10000, 65536));
+		
 		String command = Settings.PROPERTIES.getString("matlab.path",
 				OsType.getOsType() == OsType.WINDOWS ? "matlab.exe" : "matlab");