Commands

Running the programs

The most general way is to use the python -m terminal command for the program for the desired mode.

User mode

The command for user mode is

$ python -m bootsp.user_boot module arguments

where module is the name of a Python module (without .py, even though the file name itself has .py) such as farmer that contains a scenario creator with helper functions and arguments is list of double-dash-intiated Arguments. names, usually with an argument value such as --solver-name cplex. A fairly long list of arguments is required in user mode, which is why most users put their command lines in a shell script (e.g., a bash script such as farmer.bash).

Simulation mode

The command for simulation mode is

$ python -m bootsp.simulate_boot filename

where filename is the name of a Python such as farmer.json that contains a full Arguments set for the simulation.

Arguments

Simulation and user modes use almost the same arguments, but they are formatted a little bit differently. In simulation mode, some of the arguments have underscores, but not dashes. In user mode, some arguments have dashes, but none have underscores. For example, there is a solver_name argument in simulation mode and a solver-name argument in user mode.

In simulation mode, the argument values are given in a json file, while in user mode, they are given on the command line. Here is a list of arguments giving the with the simulation mode version, the user mode version and some discusion. In the json format, all string values are quote delimited.

  • max_count, --max-count: The total sample size given as an integer such as 100.

  • module_name, n/a: The name of of the python module that has the scenario creator and help functions given in the json file as a string such as “farmer”. There is not command line argument name for this in user mode, where the module name is given as the first argument without an argument name.

  • xhat_fname, --xhat-fname: When xhat (the estimated, or candidate) solution is computed by another program (which is common and recommended in simulation mode), this argument gives the name of an numpy file that has the solution as string such as “xhat.npy”. If there is no file, the value should be the string “None”. One way to create such a file is to use boot_general_prep

  • optimal_fname, n/a: This gives the file name for an optimal (or presumed optimal) solution in a format written by mpi-sppy code. The name is given as as a string such as “schultz_optimal.npy” and is ignored in user mode. If the name “None” is given, the software will compute an estimated global optimum using max_count scenarios. One way to create such a file is to use boot_general_prep.

  • candidate_sample_size, --candidate-sample-size: The boot-sp software can call a function in the module to generate an xhat solution (see the Optional module functions section). This argument provides the sample size. It corresponds to the paramater M given in the paper. It is given as an intger such as 25. If the xhat_fname argument is not “None”, then candidate_sample_size is ignored.

  • sample_size, --sample-size: This value is the sample size used to for bootstrap or bagging. It corresponds to N in the paper and is given as an integer such as 75.

  • subsample_size, --subsample-size: The subsample size used for bagging. It is given as an integer such as 10. It is ignored for bootstrap methods.

  • nB, --nB: The number of subsamples to take. It is given as an intger such as 10.

  • alpha, --alpha: significance level for the confidence intervals. It is given as a floating point number such as 0.05 for 95% confidence.

  • seed_offset, --seed-offset : This option is provided so that modelers who want to enable replication with difference seeds can do so. For some instances it can be used to assure independence between the psuedo-random number streams used to compute xhat and those used for confidence interval estimation. It is given as an integer. Unless you have a reason to do otherwise, just use 0, or, in user-mode, don’t supply it.

  • solver_name, --solver-name: The name of the solver to be used given as a string such as “gurobi_direct”.

  • trace_fname, n/a: This is usually “None”, but if it is not none the named file is opened in append mode and information about the simulation is written. Since the file is opned to append, it must already exist.

  • coverage_replications, n/a: For simulations, this controls the number of replications used to computed coverage. It is an integer, e.g. 100.

  • boot_method, --boot-method: The method given as a string. Here are the choices (underscores in the string tokens are used in user and simulation mode):

In addition to these arguments, there may be problem-specific arguments (e.g. “crops_multiplier” for the scalable farmer problem).

Farmer Examples

For these two examples, cd to boot-sp/examples/farmer.

simulate

$ python -m bootsp.simulate_boot farmer.json

user

$ python -m bootsp.user_boot farmer --max-count 121 --candidate-sample-size 1 --sample-size 75 --subsample-size 10 --nB 10 --alpha 0.05 --seed-offset 100  --solver-name cplex --boot-method Bagging_with_replacement --xhat-fname farmer_xhat.npy

Note that in this particular command --candidate-sample-size 1 is ignored because a precomputed xhat is provided by --xhat-fname farmer_xhat.npy