linny-r 1.4.1 → 1.4.3

package/README.md

@@ -25,7 +25,7 @@ Technical documentation will be developed on GitHub: https://github.com/pwgbots/
 Linny-R is developed as a JavaScript package, and requires that **Node.js** is installed on your computer. 
 This software can be downloaded from <a href="https://nodejs.org" target="_blank">https://nodejs.org</a>. 
 Make sure that you choose the correct installer for your computer.
-Linny-R is developed using the _current_ release. Presently (June 2023) this is 20.3.0. 
+Linny-R is developed using the _current_ release. Presently (August 2023) this is 20.5.1. 
 
 Run the installer and accept the default settings.
 There is **no** need to install the optional _Tools for Native Modules_.
@@ -36,33 +36,33 @@ Verify the installation by typing:
 
 ``node --version``
 
-The response should be the version number of Node.js, for example: v20.3.0.
+The response should be the version number of Node.js, for example: v20.5.1.
 
 ## Installing Linny-R
 It is advisable to install Linny-R in a directory on your computer, not in a cloud. 
-In this installation guide, the path to this directory is denoted by `WORKING_DIRECTORY`,
+In this installation guide, the path to this directory is denoted by `Linny-R`,
 so in all commands you should replace this with the actual directory path.
-On a Windows machine you may choose something like `C:\Users\xyz\Documents\Linny-R`,
-and on a macOS machine probably `/Users/xyz/Linny-R`.
+On a Windows machine the suggested path is `C:\Users\(your user name)\Documents\Linny-R`,
+and on a macOS machine `/Users/(your user name)/Linny-R`.
 
 To install Linny-R in this directory, first create it:
 
-``mkdir WORKING_DIRECTORY``
+``mkdir Linny-R``
 
 then change to it:
 
-``cd WORKING_DIRECTORY``
+``cd Linny-R``
 
 and then type at the command line prompt: 
 
 ``npm install --prefix . linny-r``
 
-**NOTE:** The spacing around the dot is important.
+**NOTE:** The spacing around the dot is important. Type the command in lower case.
 
-After installation has completed, `WORKING_DIRECTORY` should have this directory tree structure:
+After installation has completed, `Linny-R` should have this directory tree structure:
 
 <pre>
-WORKING_DIRECTORY
+Linny-R
  |
  +-node_modules
     |
@@ -81,7 +81,7 @@ WORKING_DIRECTORY
           +-sounds
 </pre>
 
-`WORKING_DIRECTORY` should contain two JSON files `package.json` and `package-lock.json`
+`Linny-R` should contain two JSON files `package.json` and `package-lock.json`
 that should **not** be removed, or you will have to re-install Linny-R. It should also contain
 a script file to facilitate (single click) launch: on a macOS machine the shell script `linny-r.command`,
 on a Windows machine the batch script `linny-r.bat`. By default, this script file contains
@@ -109,17 +109,18 @@ The sub-directories of `static` contain files that are served to the browser by
 
 ## Configuring the MILP solver
 
-Linny-R presently supports two MILP solvers: Gurobi  and LP_solve. 
-Gurobi is _considerably_ more powerful than the open source LP_solve solver that has powered Linny-R since 2009,
-but it requires a license.
+Linny-R presently supports four MILP solvers: Gurobi, CPLEX, SCIP and LP_solve. 
+Gurobi and CPLEX are _considerably_ more powerful than the open source solvers SCIP and LP_solve,
+but they require a license.
 Academic licenses can be obtained by students and staff of eligible institutions. 
 
 #### Installing Gurobi
 
-The software you need to install is '''Gurobi Optimizer'''.
+The software you need to install is **Gurobi Optimizer**.
 More information on how to obtain a license, and instructions for installing
 Gurobi on your computer can be obtained via this URL:
-https://www.gurobi.com/academia/academic-program-and-licenses/
+<a href="https://www.gurobi.com/academia/academic-program-and-licenses/"
+   target="_blank">https://www.gurobi.com/academia/academic-program-and-licenses/</a>
 
 When running a model, Linny-R will try to execute the command line application `gurobi_cl`.
 It will look for this application in the directory specified in the environment variable PATH on your computer.
@@ -127,23 +128,51 @@ It will look for this application in the directory specified in the environment
 When installing Gurobi, please accept the default file locations that are proposed by the installer.
 Then do **not** move Gurobi files to some other directory, as this is bound to cause problems.
 
+#### Installing CPLEX
+
+The software you need to install is **CPLEX**.
+More information on how to obtain a license, and instructions for installing
+CPLEX on your computer can be obtained via this URL:
+<a href="https://www.ibm.com/products/ilog-cplex-optimization-studio"
+   target="_blank">https://www.ibm.com/products/ilog-cplex-optimization-studio</a>
+
+When running a model, Linny-R will try to execute the command line application `cplex`.
+It will look for this application in the directory specified in the environment variable PATH
+or more specifically in the environment variable CPLEX_STUDIO_BINARIES<em>nnnn</em>
+(where _nnnn_ denotes the CPLEX version number) on your computer.
+
+When installing CPLEX, please accept the default file locations that are proposed by the installer.
+Then do **not** move CPLEX files to some other directory, as this is bound to cause problems.
+
+#### Installing SCIP
+
+The SCIP software is open source. Instructions for installation can be found via this URL:
+<a href="https://scipopt.org/doc/html/INSTALL.php" target="_blank">https://scipopt.org/doc/html/INSTALL.php</a>
+
+When running a model, Linny-R will try to execute the command line application `scip`.
+It will look for this application in the directory specified in the environment variable PATH on your computer.
+
+When installing SCIP, please accept the default file locations that are proposed by the installer.
+Then do **not** move SCIP files to some other directory, as this is bound to cause problems.
+
 #### Installing LP_solve
 
 The LP_solve software is open source and can be downloaded via this URL:
-https://sourceforge.net/projects/lpsolve
+<a href="https://sourceforge.net/projects/lpsolve" target="_blank">https://sourceforge.net/projects/lpsolve</a>
 
-To facilitate installation, the executable files for Windows and macOS can be downloaded from the Linny-R website at Delft University of Technology:
-https://sysmod.tbm.tudelft.nl/linny-r/lp_solve
+To facilitate installation, the executable files for Windows and macOS can be downloaded from the Linny-R website
+at Delft University of Technology:
+<a href="https://sysmod.tbm.tudelft.nl/linny-r/lp_solve" target="_blank">https://sysmod.tbm.tudelft.nl/linny-r/lp_solve</a>
 
 There you will find links to download LP_solve applications that have been compiled for different platforms.
 If you do not know which platform to choose, run Linny-R as described below, and the platform will be listed in its output.
 If no matching LP_solve version is listed, you can try to compile the software from its source.
 How to do this is explained on the page "Installing LP_solve on a Mac" on the Linny-R documentation site:
-https://linny-r.info 
+<a href="https://linny-r.info" target="_blank">https://linny-r.info</a> 
 
 When you have downloaded the file (just `lp_solve` for macOS, `lp_solve.exe` for Windows), 
-you must copy or move this file to your `WORKING_DIRECTORY`,
-as this is where Linny-R will look for it when it does not find Gurobi.
+you must copy or move this file to your `Linny-R` directory,
+as this is where Linny-R will look for it when it does not find one of the other solvers.
 
 On a macOS machine, you must then make the file `lp_solve` executable.
 Open Terminal and change to your Linny-R directory, and then type:
@@ -163,15 +192,15 @@ If you reach this stage, Linny-R will be able to run LP_solve.
 
 ## Running Linny-R
 
-Open the Command Line Interface (CLI) of your computer, change to your `WORKING_DIRECTORY` and type:
+Open the Command Line Interface (CLI) of your computer, change to your Linny-R directory and type:
 
 ``node node_modules/linny-r/server launch``
 
 This response should be something similar to:
 
 <pre>
-Node.js server for Linny-R version 1.2.1
-Node.js version: v20.3.0
+Node.js server for Linny-R version 1.4.2
+Node.js version: v20.5.1
 ... etc.
 </pre>
 
@@ -181,9 +210,9 @@ The Linny-R GUI should show in your browser window,
 while in the CLI you should see a long series of server log messages like:
 
 <pre>
-[2023-04-29 22:55:17] Static file: /index.html
-[2023-04-29 22:55:17] Static file: /scripts/iro.min.js
-[2023-04-29 22:55:17] Static file: /images/open.png
+[2023-08-29 22:55:17] Static file: /index.html
+[2023-08-29 22:55:17] Static file: /scripts/iro.min.js
+[2023-08-29 22:55:17] Static file: /images/open.png
 ... etc.
 </pre>
 
@@ -222,7 +251,7 @@ Optionally, you can add more arguments to the `node` command:
 dpi=[number]       to overrule the default resolution (300 dpi) for Inkscape 
 launch             to automatically launch Linny-R in your default browser
 port=[number]      to overrule the default port number (5050)
-solver=[name]      to overrule the default sequence (Gurobi, LP_solve)
+solver=[name]      to overrule the default sequence (Gurobi, CPLEX, SCIP, LP_solve)
 workspace=[path]   to overrule the default path for the user directory
 </pre>
 
@@ -237,14 +266,14 @@ The dialog that then appears will allow you to go to the sub-folder `node_module
 where you should select the file `linny-r.ico`.
 Finally, rename the shortcut to `Linny-R` and move or copy it to your desktop.
 
-On a macOS machine, open _Terminal_ and change to your Linny-R directory, and then type:
+On a macOS machine, open Terminal and change to your Linny-R directory, and then type:
 
 ``chmod +x linny-r.command``
 
 to make the script file executable.
-To set the icon, open the folder that contains the file `linny-r.command`,
+To set the icon, use Finder to open the folder that contains the file `linny-r.command`,
 click on its icon (which still is plain) and open the _Info dialog_ by pressing ``Cmd+I``.
-Then open your Linny-R folder in _Finder_, change to the sub-folder `node_modules/linny-r/static/images`, 
+Then open your Linny-R folder in Finder, change to the sub-folder `node_modules/linny-r/static/images`, 
 and from there drag/drop the file `linny-r.icns` on the icon shown in the top left corner of the _Info dialog_.
 
 ## User workspace
@@ -254,13 +283,17 @@ The sub-directories of this directory `user` are used by Linny-R to store files.
 
 * `autosave` will contain models that have been _auto-saved_ 
 * `channel` and `callback` will be used to interact with Linny-R via its _Receiver_ 
+* `data` will be used by the _Dataset Manager_ to locate datasets for which a path
+  has been specified
 * `diagrams` will be used to render Scalable Vector Graphics (SVG) files as
   Portable Network Graphics (PNG) using Inkscape (if installed)
 * `modules` will contain models stored in the `local host` _repository_
+* `reports` will contain text files with time series data and statistics in tab-separated
+  format that can be imported or copy/pasted into Excel
 * `solver` will contain the files that are exchanged with the Mixed Integer Linear Programming (MILP) solver
   (the names of the files that will appear in this directory may vary, depending on the MILP-solver you use)
 
-By default, the `user` directory is created in your `WORKING_DIRECTORY`.
+By default, the `user` directory is created in your `Linny-R` directory.
 You can overrule this by specifying the path to another directory when you start the server.
 Note that doing this will create a new, empty workspace (the directories listed above)
 in the specified path. It will **not** affect or duplicate information from existing workspaces.
@@ -281,7 +314,8 @@ Meanwhile, the browser will have opened a new tab that will be "waiting" for thi
 If rendering was successful, the image will appear in this browser tab; 
 if rendering failed, the original SVG image will be shown.
 
-To install Inkscape, please look here: https://inkscape.org/release
+To install Inkscape, please look here:
+<a href="https://inkscape.org/release" target="_blank">https://inkscape.org/release</a>
 
 Linny-R will automatically detect whether Inkscape is installed by searching for it in the environment variable PATH on your computer.
 On a macOS computer, Linny-R will look for Inkscape in /Applications/Inkscape.app/Contents/MacOS.
@@ -293,7 +327,7 @@ Please check whether you need to do this yourself.
 
 The console-only version of Linny-R allows you to run a Linny-R model without a web browser.
 This may be useful when you want run models from a script (shell script, Python, ...). 
-If you open a CLI box, change to your `WORKING_DIRECTORY`, and then type:
+If you open a CLI box, change to your `Linny-R` directory, and then type:
 
 ``node node_modules/linny-r/console``  _(on Windows, use backslashes)_
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "linny-r",
-  "version": "1.4.1",
+  "version": "1.4.3",
   "description": "Executable graphical language with WYSIWYG editor for MILP models",
   "main": "server.js",
   "scripts": {

package/server.js

@@ -87,9 +87,10 @@ function getVersionInfo() {
     info.current_time = new Date(Date.parse(obj.time[info.current]));
     info.up_to_date = info.current === info.latest;
   } catch(err) {
-    // `latest` = 0 indicates that version check failed
+    // `latest` = 0 indicates that version check failed.
     info.latest = 0;
   }
+  clearNewerVersion();
   if(!info.latest) {
     console.log(connectionErrorText('Could not connect to https://registry.npmjs.org/'));
   } else if(!info.up_to_date) {
@@ -145,12 +146,13 @@ const SOLVER = new MILPSolver(SETTINGS, WORKSPACE);
 // Create launch script
 createLaunchScript();
 
-// Create the HTTP server
+// Create the HTTP server.
 const SERVER = http.createServer((req, res) => {
     const u = new URL(req.url, 'http://127.0.0.1:' + SETTINGS.port);
-    // When POST, first get all the full body
+    // When POST, first get all the full body.
     if(req.method === 'POST') {
       let body = '';
+      // @@TO DO: For big data requests, string may become too long.
       req.on('data', (data) => body += data);
       req.on('end', () => processRequest(req, res, u.pathname, body));
     } else if(req.method === 'GET') {
@@ -198,7 +200,7 @@ function logAction(msg) {
 
 function autoCheck(res) {
   // Serves a string with the current version number plus info on a
-  // newer release if this is available
+  // newer release if this is available.
   let check = VERSION_INFO.current + '|';
   if(VERSION_INFO.up_to_date) {
     check += 'up-to-date';
@@ -208,22 +210,46 @@ function autoCheck(res) {
   servePlainText(res, check);
 }
 
-// HTML page to show then the server is shut down by the user
+function setNewerVersion() {
+  // Creates the file "newer_version" in the working directory, so that
+  // when the server is run from the standard batch script it will detect
+  // that an update is required.
+  const nvf = path.join(WORKING_DIRECTORY, 'newer_version');
+  try {
+    fs.writeFileSync(nvf, VERSION_INFO.latest);
+  } catch(err) {
+    console.log('WARNING: Failed to create file:', nvf);
+    console.log(err);
+  }
+}
+
+function clearNewerVersion() {
+  // Forestalls auto-update by deleting the file "newer_version" that may
+  // have been created at start-up from the working directory.
+  try {
+    fs.unlink(path.join(WORKING_DIRECTORY, 'newer_version'));
+  } catch(err) {
+    // No action, as error is nogt fatal.
+  }
+}
+
+// HTML page to show when the server is shut down by the user.
 // NOTE: on a macOS machine, this is slightly more work
-const
-    OS_TEXT = (PLATFORM === 'darwin' ? [
+const OS_TEXT = {close: '', reopen: ''};
+if(PLATFORM === 'darwin') {
+  OS_TEXT.close =
 `<p>You can close the <em>Terminal</em> window that shows
   <tt>[Process Terminated]</tt> at the bottom.
-</p>`,
+</p>`;
+  OS_TEXT.reopen =
 `open <em>Terminal</em> again, change to your Linny-R directory by typing:
 </p>
 <p><code>cd ${WORKING_DIRECTORY}</code></p>
-<p>`
-      ] : [
-'',
-'switch to your <em>Command Prompt</em> window '
-      ]),
-    SHUTDOWN_MESSAGE = `<!DOCTYPE html>
+<p>`;
+} else {
+  OS_TEXT.reopen = 'switch to your <em>Command Prompt</em> window ';
+}
+const SHUTDOWN_MESSAGE = `<!DOCTYPE html>
 <html lang="en-US">
 <head>
   <meta http-equiv="content-type" content="text/html; charset=UTF-8">
@@ -243,13 +269,8 @@ const
   </style>
 </head>
 <body>
-  <h3>Linny-R server (127.0.0.1) is shutting down</h3>` + OS_TEXT[0] + `
-  <p>To restart Linny-R, ` + OS_TEXT[1] + ` and then at the prompt` +
-(VERSION_INFO.up_to_date ? '' : `
-  first type:</p>
-  <p><code>npm update linny-r</code><p>
-  to upgrade to Linny-R version ${VERSION_INFO.latest}, and then`) +
-` type:</p>
+  <h3>Linny-R server (127.0.0.1) is shutting down</h3>${OS_TEXT.close}
+  <p>To restart Linny-R, ${OS_TEXT.reopen} and then at the prompt type:</p>
   <p><code>node node_modules${path.sep}linny-r${path.sep}server</code></p>
   <p>
     Then switch back to this window, and click this
@@ -1064,7 +1085,7 @@ function rcvrReport(res, rpath, rfile, run, data, stats, log) {
         }
       }
     }
-    if(n) console.log(n + 'report file' + (n > 1 ? 's' : '') + 'purged');
+    if(n) console.log(n + ' report file' + (n > 1 ? 's' : '') + ' purged');
   } catch(err) {
     // Log error, but do not abort.
     console.log(err);
@@ -1207,16 +1228,20 @@ function processRequest(req, res, cmd, data) {
   // NOTE: `data` is a string of form field1=value1&field2=value2& ... etc.
   // regardless of the request method (GET or POST)
   if(permittedFile(cmd)) {
-    // Path contains valid MIME file type extension => serve if allowed
+    // Path contains valid MIME file type extension => serve if allowed.
     serveStaticFile(res, cmd);
-  } else if(cmd === '/solver/') {
+    return;
+  }
+  // Be permissive w.r.t. leading and trailing slashes.
+  cmd = cmd.replace(/^\/+/, '').replace(/\/+$/, '');
+  if(cmd === 'solver') {
     const
         sp = new URLSearchParams(data),
         action = sp.get('action');
-    // NOTE: on remote servers, solver actions require authentication
+    // NOTE: On remote servers, solver actions require authentication.
     if(action === 'logon') {
-      // No authentication -- simply return the passed token, "local host" as
-      // server name, and the identifier of the solver
+      // No authentication -- simply return the passed token, "local host"
+      // as server name, and the identifier of the solver.
       serveJSON(res,
           {token: 'local host', server: 'local host', solver: SOLVER.id});
     } else if(action === 'png') {
@@ -1229,19 +1254,40 @@ function processRequest(req, res, cmd, data) {
       console.log(msg);
       serveJSON(res, {error: msg});
     }
-  } else if(cmd === '/shutdown') {
-    // Shut down this server
+  } else if(cmd === 'shutdown') {
+    // Shut down this server WITHOUT updating, and show page with
+    // "shut down" message and restart button.
+    clearNewerVersion();
     serveHTML(res, SHUTDOWN_MESSAGE);
     SERVER.close();
-  } else if(cmd === '/auto-check') {
+  } else if(cmd === 'version') {
+    logAction('HERE version = ' + VERSION_INFO.current);
+    servePlainText(res, 'Current version is ' + VERSION_INFO.current);
+  } else if(cmd === 'update') {
+    // Shut down this server silently. When the server was started from
+    // a batch script, this will update via npm, and then restart.
+    // NOTE: Self-protect against overwriting development scripts.
+    if(WORKING_DIRECTORY.indexOf('LTR3') >= 0) {
+      servePlainText(res, 'No version update in development environment');
+    } else {
+      setNewerVersion();
+      servePlainText(res, 'Installing Linny-R version ' + VERSION_INFO.latest);
+      SERVER.close();
+    }
+  } else if(cmd === 'no-update') {
+    // Remove file "newer_version" so no update will take place when
+    // server is shut down.
+    clearNewerVersion();
+    servePlainText(res, 'No update to version ' + VERSION_INFO.latest);
+  } else if(cmd === 'auto-check') {
     autoCheck(res);
-  } else if(cmd === '/autosave/') {
+  } else if(cmd === 'autosave') {
     autoSave(res, new URLSearchParams(data));
-  } else if(cmd === '/repo/') {
+  } else if(cmd === 'repo') {
     repo(res, new URLSearchParams(data));
-  } else if(cmd === '/load-data/') {
+  } else if(cmd === 'load-data') {
     loadData(res, (new URLSearchParams(data)).get('url'));
-  } else if(cmd === '/receiver/') {
+  } else if(cmd === 'receiver') {
     receiver(res, new URLSearchParams(data));
   } else {
     serveJSON(res, {error: `Unknown Linny-R request: "${cmd}"`});
@@ -1249,7 +1295,7 @@ function processRequest(req, res, cmd, data) {
 }
 
 function servePlainText(res, msg) {
-  // Serve string `msg` as plain text
+  // Serve string `msg` as plain text.
   res.setHeader('Content-Type', 'text/plain');
   res.writeHead(200);
   res.end(msg);
@@ -1698,28 +1744,53 @@ function createLaunchScript() {
   // Creates platform-specific script with Linny-R start-up command
   const lines = [
       '# The first line (without the comment symbol #) should be like this:',
-      '# cd ',
+      '',
       '',
       '# Then this command to launch the Linny-R server should work:',
-      'node ' + path.join('node_modules', 'linny-r', 'server') + ' launch'
+      '',
+      '# After shut-down, check whether new version should be installed:'
     ];
+  lines[2] = 'cd ' + WORKING_DIRECTORY;
   let sp;
   if(PLATFORM.startsWith('win')) {
     sp = path.join(WORKING_DIRECTORY, 'linny-r.bat');
-    lines[1] += 'C:\\path\\to\\main\\Linny-R\\directory';
+    lines.push(
+      ':loop',
+      'if exist newer_version (',
+      '    del newer_version',
+      '    npm update linny-r',
+      '    node node_modules\\linny-r\\server',
+      '    goto loop',
+      ')');
+    lines[1] = '# cd C:\\path\\to\\main\\Linny-R\\directory';
+    lines[4] = 'node node_modules\\linny-r\\server launch';
   } else {
     sp = path.join(WORKING_DIRECTORY, 'linny-r.command'); 
-    lines[1] += '/path/to/main/Linny-R/directory';
+    lines.push(
+      'while test -f newer_version; do',
+      '    unlink newer_version',
+      '    npm update linny-r',
+      '    node node_modules/linny-r/server',
+      'done');
+    lines[1] = '# cd /path/to/main/Linny-R/directory';
+    lines[4] = 'node node_modules/linny-r/server launch';
   }
-  lines[2] = 'cd ' + WORKING_DIRECTORY;
   try {
+    let make_script = false,
+        code = lines.join(os.EOL);
+    if(PLATFORM.startsWith('win')) code = code.replaceAll('#', '::');
     try {
       fs.accessSync(sp);
+      // Only write the script content if the file has not been customized
+      // by the user...
+      const data = fs.readFileSync(sp, 'utf-8');
+      make_script = code.indexOf(data) >= 0;
     } catch(err) {
-      // Only write the script content if the file it does not yet exist
+      // ... or if it does not exist yet.
+      make_script = true;
+    }
+    if(make_script) {
       console.log('Creating launch script:', sp);
-      let code = lines.join(os.EOL);
-      if(PLATFORM.startsWith('win')) code = code.replaceAll('#', '::');
       fs.writeFileSync(sp, code, 'utf8');
     }
   } catch(err) {