toc

Author: kyle cooper

README.md

@@ -22,13 +22,13 @@ Table of Contents
          * [Install latest trunk version from git](#install-latest-trunk-version-from-git)
          * [Install from source](#install-from-source)
       * [CLI](#cli)
-            * [listitems](#listitems)
-            * [solve](#solve)
-            * [testsolve](#testsolve)
-            * [Output](#output)
-            * [Table of options for solve and testsolve](#table-of-options-for-solve-and-testsolve)
-            * [Table of algorithm-specific parameters](#table-of-algorithm-specific-parameters)
-      * [Programming guide](#programming-guide)
+         * [listitems](#listitems)
+         * [solve](#solve)
+         * [testsolve](#testsolve)
+         * [Output](#output)
+         * [Table of options for solve and testsolve](#table-of-options-for-solve-and-testsolve)
+         * [Table of algorithm-specific parameters](#table-of-algorithm-specific-parameters)
+      * [Implementing problems, testers, and algorithms in PyMOSO](#implementing-problems-testers-and-algorithms-in-pymoso)
          * [Implementing a problem in PyMOSO](#implementing-a-problem-in-pymoso)
             * [Template for implementing problems (myproblem.py)](#template-for-implementing-problems-myproblempy)
             * [Using rng](#using-rng)
@@ -118,19 +118,19 @@ Help:
   test problems.
 ```
 For now, PyMOSO has three commands: `listitems`, `solve`, and `testsolve`, which we explain below.
-#### listitems
+### listitems
 The command `listitems` shows the PyMOSO objects (problems, testers, solvers) included in the default installation. The identifiers can be used as arguments to `solve` and `testsolve`. PyMOSO objects implemented by users will not show up when using `listitems`.
-#### solve
+### solve
 The `solve` command is intended for practitioners seeking to a solve a simulation optimization problem. Three arguments are required: `<problem>`, `<solver>`, and  `<x>...`. For `<problem>`, users may specify an identifier for a built-in problem. A list of such identifiers can be viewed using `listitems`. Alternatively, users may implement their own problem as a PyMOSO oracle (see the code examples below) and specify the file name.
 For example,  
 `pymoso solve myproblem.py RPERLE 40 40`  
 The `<solver>` argument again either an identifier to a built-in algorithm, or a file name for a user-implemented algorithm. The `<x>...` is a feasible starting point for the algorithm, with each component of the starting point separated by a space. Any number of the options listed above can also be specified before the arguments. At the end of this section, we list the options and provide more detailed explanations. The `<x>` argument cannot take negative numbers from the command line. Use PyMOSO in a Python program if a negative starting point is required (see examples below).   
-#### testsolve
+### testsolve
 The `testsolve` command is intended for researchers creating new simulation optimization algorithms.  Two arguments are required: `<tester>` and `<solver>`. Similar to `solve`, `<tester>` and `<solver>` may be specified as identifiers to built-in testers or as Python files containing user-implemented objects. Specifying `<x>...` is optional: testers may implement a method to generate feasible starting points. If not, then `<x>...` can be provided.  
-#### Output
+### Output
 Both `solve` and `testsolve` create a subdirectory within the working directory in which the generated results are saved. In the case of `solve`, the directory typically contains two files: a file containing metadata such as the arguments and options specified, date, run time, and more. The second file contains the solution generated by the chosen solver. If applicable, an error file may be generated. If an error is generated, users may send the metadata file, the error file, and any user-implemented PyMOSO objects to us for assistance. In the case of `testsolve`, the file containing the solution will instead contain multiple solutions, with the last row containing the end solution returned by the algorithm. The intermediate solutions are provided to give a researchers a sense of how the algorithm progresses. If the `--isp` option is specified to generate multiple independent sample path solutions, there will a solution file for every independent sample path. If the `--metric` options is specified, the metric defined in the `<tester>` will be computed on the solutions and saved in a separate file.  All available options to `solve` or `testsolve` are specified below.  
 
-#### Table of options for solve and testsolve
+### Table of options for solve and testsolve
 | Option | Description |
 | ----------- | ----------- |
 |`--budget=B`| The simulation budget limits the number of simulations the algorithm can use to generate a solution. `B` should be a natural number. |
@@ -144,7 +144,7 @@ Both `solve` and `testsolve` create a subdirectory within the working directory
 |`--param <param> <val>`| Specify a parameter by name and value. These are algorithm-specific parameters.|
 
 
-#### Table of algorithm-specific parameters
+### Table of algorithm-specific parameters
 | Algorithm | Parameter | Default | Description |
 | --------- | --------- | ------- | ----------- |
 | `RPERLE`, `RMINRLE`, `RPE`, `RSPLINE` | `mconst` | `2` | Sets the initial sample size, and subsequent schedule of sample sizes. |
@@ -153,7 +153,7 @@ Both `solve` and `testsolve` create a subdirectory within the working directory
 | `RPERLE`, `RMINRLE` | `betadel` | `0.5` | Roughly, affects how likely it is for RLE to keep its given solution. See http://www.optimization-online.org/DB_HTML/2018/06/6649.html. |
 | `RPERLE` and `RPE` | `betaeps` | `0.5`   | Roughly, affects how likely PE will perform a search from a point. See http://www.optimization-online.org/DB_HTML/2018/06/6649.html. |
 
-## Programming guide
+## Implementing problems, testers, and algorithms in PyMOSO
 ### Implementing a problem in PyMOSO
 Users can implement their own problems in PyMOSO using `myproblem.py` below as the template. The function signatures of `__init__` and `g` must remain the same as shown. Furthermore, in `__init__`, the only changes will be to set `self.num_obj` and `self.dim` as appropriate. The `g` function needs to implement a single simulation observation at `x`, a Python tuple of length `self.dim` representing some point. The function `g` can be a wrapper to external simulation or other programs, but must return two values:
 1. `True` or `False` depending on if `x` is feasible to the problem.