From 434c3351a04b131a89903d610a71215b4d287241 Mon Sep 17 00:00:00 2001 From: William Grochocinski Date: Wed, 5 Mar 2025 15:00:43 -0500 Subject: [PATCH 1/3] reorganized documentation structure to match standard layout --- docs/{ => _static}/amusementpark.png | Bin docs/{ => _static}/contam.PNG | Bin docs/{ => _static}/hotel.PNG | Bin docs/{ => _static}/hotel2.PNG | Bin docs/{ => _static}/san.PNG | Bin docs/{ => _static}/sscont.png | Bin docs/{ => _templates}/model_template.rst | 208 ++++++------ docs/{ => _templates}/solver_template.rst | 82 ++--- docs/{ => source}/GUI.rst | 14 +- docs/{ => source}/adam.rst | 142 ++++---- docs/{ => source}/aloe.rst | 150 ++++----- docs/{ => source}/amusementpark.rst | 306 ++++++++--------- docs/{ => source}/astrodf.rst | 164 +++++----- docs/{ => source}/base.rst | 14 +- docs/{ => source}/chessmm.rst | 214 ++++++------ docs/{ => source}/cntnv.rst | 222 ++++++------- docs/{ => source}/conf.py | 8 +- docs/{ => source}/contam.rst | 374 ++++++++++----------- docs/{ => source}/data_farming_base.rst | 14 +- docs/{ => source}/directory.rst | 14 +- docs/{ => source}/dualsourcing.rst | 276 ++++++++-------- docs/{ => source}/dynamnews.rst | 250 +++++++------- docs/{ => source}/experiment_base.rst | 14 +- docs/{ => source}/facilitysizing.rst | 308 +++++++++--------- docs/{ => source}/hotel.rst | 380 +++++++++++----------- docs/{ => source}/index.rst | 92 +++--- docs/{ => source}/ironore.rst | 308 +++++++++--------- docs/{ => source}/main.rst | 14 +- docs/{ => source}/mm1queue.rst | 188 +++++------ docs/{ => source}/models.rst | 266 +++++++-------- docs/{ => source}/modules.rst | 16 +- docs/{ => source}/neldmd.rst | 130 ++++---- docs/{ => source}/network.rst | 220 ++++++------- docs/{ => source}/paramesti.rst | 178 +++++----- docs/{ => source}/prodsys.rst | 298 ++++++++--------- docs/{ => source}/randomsearch.rst | 74 ++--- docs/{ => source}/rmitd.rst | 262 +++++++-------- docs/{ => source}/san.rst | 194 +++++------ docs/{ => source}/simopt.models.rst | 314 +++++++++--------- docs/{ => source}/simopt.rst | 124 +++---- docs/{ => source}/simopt.solvers.rst | 138 ++++---- docs/{ => source}/solvers.rst | 90 ++--- docs/{ => source}/spsa.rst | 128 ++++---- docs/{ => source}/sscont.rst | 76 ++--- docs/{ => source}/strong.rst | 188 +++++------ docs/{ => source}/tableallocation.rst | 206 ++++++------ docs/{ => source}/test.rst | 58 ++-- 47 files changed, 3357 insertions(+), 3359 deletions(-) rename docs/{ => _static}/amusementpark.png (100%) rename docs/{ => _static}/contam.PNG (100%) rename docs/{ => _static}/hotel.PNG (100%) rename docs/{ => _static}/hotel2.PNG (100%) rename docs/{ => _static}/san.PNG (100%) rename docs/{ => _static}/sscont.png (100%) rename docs/{ => _templates}/model_template.rst (95%) rename docs/{ => _templates}/solver_template.rst (95%) rename docs/{ => source}/GUI.rst (93%) rename docs/{ => source}/adam.rst (97%) rename docs/{ => source}/aloe.rst (96%) rename docs/{ => source}/amusementpark.rst (97%) rename docs/{ => source}/astrodf.rst (97%) rename docs/{ => source}/base.rst (93%) rename docs/{ => source}/chessmm.rst (96%) rename docs/{ => source}/cntnv.rst (96%) rename docs/{ => source}/conf.py (96%) rename docs/{ => source}/contam.rst (96%) rename docs/{ => source}/data_farming_base.rst (95%) rename docs/{ => source}/directory.rst (94%) rename docs/{ => source}/dualsourcing.rst (96%) rename docs/{ => source}/dynamnews.rst (96%) rename docs/{ => source}/experiment_base.rst (95%) rename docs/{ => source}/facilitysizing.rst (96%) rename docs/{ => source}/hotel.rst (97%) rename docs/{ => source}/index.rst (98%) rename docs/{ => source}/ironore.rst (96%) rename docs/{ => source}/main.rst (93%) rename docs/{ => source}/mm1queue.rst (95%) rename docs/{ => source}/models.rst (94%) rename docs/{ => source}/modules.rst (88%) rename docs/{ => source}/neldmd.rst (97%) rename docs/{ => source}/network.rst (97%) rename docs/{ => source}/paramesti.rst (96%) rename docs/{ => source}/prodsys.rst (96%) rename docs/{ => source}/randomsearch.rst (96%) rename docs/{ => source}/rmitd.rst (96%) rename docs/{ => source}/san.rst (96%) rename docs/{ => source}/simopt.models.rst (94%) rename docs/{ => source}/simopt.rst (93%) rename docs/{ => source}/simopt.solvers.rst (94%) rename docs/{ => source}/solvers.rst (94%) rename docs/{ => source}/spsa.rst (96%) rename docs/{ => source}/sscont.rst (98%) rename docs/{ => source}/strong.rst (96%) rename docs/{ => source}/tableallocation.rst (96%) rename docs/{ => source}/test.rst (93%) diff --git a/docs/amusementpark.png b/docs/_static/amusementpark.png similarity index 100% rename from docs/amusementpark.png rename to docs/_static/amusementpark.png diff --git a/docs/contam.PNG b/docs/_static/contam.PNG similarity index 100% rename from docs/contam.PNG rename to docs/_static/contam.PNG diff --git a/docs/hotel.PNG b/docs/_static/hotel.PNG similarity index 100% rename from docs/hotel.PNG rename to docs/_static/hotel.PNG diff --git a/docs/hotel2.PNG b/docs/_static/hotel2.PNG similarity index 100% rename from docs/hotel2.PNG rename to docs/_static/hotel2.PNG diff --git a/docs/san.PNG b/docs/_static/san.PNG similarity index 100% rename from docs/san.PNG rename to docs/_static/san.PNG diff --git a/docs/sscont.png b/docs/_static/sscont.png similarity index 100% rename from docs/sscont.png rename to docs/_static/sscont.png diff --git a/docs/model_template.rst b/docs/_templates/model_template.rst similarity index 95% rename from docs/model_template.rst rename to docs/_templates/model_template.rst index e35aba088..ce7018a8b 100644 --- a/docs/model_template.rst +++ b/docs/_templates/model_template.rst @@ -1,104 +1,104 @@ -Model: () -========================================== - -Description: ------------- - - -Sample math... :math:`S = 1500` - -Sample math... - -.. math:: - - \frac{ \sum_{t=0}^{N}f(t,k) }{N} - -Sources of Randomness: ----------------------- - - -Model Factors: --------------- -* : - - * Default: - -* : - - * Default: - -* : - - * Default: - -Responses: ----------- -* : - -* : - -* : - - -References: -=========== -This model is adapted from the article
- - - - -Optimization Problem: () -======================================================== - -Decision Variables: -------------------- -* -* - -Objectives: ------------ - - -Constraints: ------------- - - -Problem Factors: ----------------- -* : - - * Default: - -* : - - * Default: - -Fixed Model Factors: --------------------- -* : - -* : - -Starting Solution: ------------------- -* : - -* : - -Random Solutions: ------------------- - - -Optimal Solution: ------------------ - - -Optimal Objective Function Value: ---------------------------------- - - - -Optimization Problem: () -======================================================== - -... +Model: () +========================================== + +Description: +------------ + + +Sample math... :math:`S = 1500` + +Sample math... + +.. math:: + + \frac{ \sum_{t=0}^{N}f(t,k) }{N} + +Sources of Randomness: +---------------------- + + +Model Factors: +-------------- +* : + + * Default: + +* : + + * Default: + +* : + + * Default: + +Responses: +---------- +* : + +* : + +* : + + +References: +=========== +This model is adapted from the article
+ + + + +Optimization Problem: () +======================================================== + +Decision Variables: +------------------- +* +* + +Objectives: +----------- + + +Constraints: +------------ + + +Problem Factors: +---------------- +* : + + * Default: + +* : + + * Default: + +Fixed Model Factors: +-------------------- +* : + +* : + +Starting Solution: +------------------ +* : + +* : + +Random Solutions: +------------------ + + +Optimal Solution: +----------------- + + +Optimal Objective Function Value: +--------------------------------- + + + +Optimization Problem: () +======================================================== + +... diff --git a/docs/solver_template.rst b/docs/_templates/solver_template.rst similarity index 95% rename from docs/solver_template.rst rename to docs/_templates/solver_template.rst index 8105517d0..96e3f198b 100644 --- a/docs/solver_template.rst +++ b/docs/_templates/solver_template.rst @@ -1,42 +1,42 @@ -Solver: () -============================================= - -Description: ------------- - - -Sample math... :math:`S = 1500` - -Sample math... - -.. math:: - - \frac{ \sum_{t=0}^{N}f(t,k) }{N} - - -Modifications & Implementation: -------------------------------- - - -Scope: ------- - - -Solver Factors: ---------------- -* : - - * Default: - -* : - - * Default: - -* : - - * Default: - - -References: -=========== +Solver: () +============================================= + +Description: +------------ + + +Sample math... :math:`S = 1500` + +Sample math... + +.. math:: + + \frac{ \sum_{t=0}^{N}f(t,k) }{N} + + +Modifications & Implementation: +------------------------------- + + +Scope: +------ + + +Solver Factors: +--------------- +* : + + * Default: + +* : + + * Default: + +* : + + * Default: + + +References: +=========== This solver is adapted from the article
\ No newline at end of file diff --git a/docs/GUI.rst b/docs/source/GUI.rst similarity index 93% rename from docs/GUI.rst rename to docs/source/GUI.rst index fd027b9bc..4d9d92ef0 100644 --- a/docs/GUI.rst +++ b/docs/source/GUI.rst @@ -1,7 +1,7 @@ -GUI module -========== - -.. automodule:: GUI - :members: - :undoc-members: - :show-inheritance: +GUI module +========== + +.. automodule:: GUI + :members: + :undoc-members: + :show-inheritance: diff --git a/docs/adam.rst b/docs/source/adam.rst similarity index 97% rename from docs/adam.rst rename to docs/source/adam.rst index f95981bf7..5085955d5 100644 --- a/docs/adam.rst +++ b/docs/source/adam.rst @@ -1,71 +1,71 @@ -Solver: ADAM -============ - -Description: ------------- -The solver is for efficient stochastic optimization that only requires first-order gradients -with little memory requirement. The method computes individual adaptive learning rates for -different parameters from estimates of first and second moments of the gradients. - - -Modifications & Implementation: -------------------------------- -At each timestep :math:`t`, we first evaluate the gradient w.r.t the current solution :math:`x`, either using -the IPA gradient estimates or finite difference estimates. -Then, the algorithm updates exponential moving averages of the gradient :math:`m_t` and the squared gradient -:math:`v_t` where the hyper-parameters :math:`\beta_1` and :math:`\beta_2` control the exponential decay rates of -these moving averages. The moving averages themselves are estimates of the 1st moment (the mean) and the -2nd raw moment (the uncentered variance) of the gradient. These moving averages are -initialized as (vectors of) 0's, leading to moment estimates that are biased towards zero, especially -during the initial timesteps, and especially when the decay rates are small (i.e., the :math:`\beta` are close to 1). -The bias-corrected estimates :math:`\hat{m_t}` and :math:`\hat{v_t}`. Lastly, the new solution can be found via -current solution, the bias-corrected first and second moment estimate, and the step size. - -Helper functions: -The finite_diff function uses finite difference methods to estimate the gradient of the -objective function. - - -Scope: ------- -* objective_type: single - -* constraint_type: box - -* variable_type: continuous - - -Solver Factors: ---------------- -* crn_across_solns: Use CRN across solutions? - - * Default: True - -* r: Number of replications taken at each solution. - - * Default: 30 - -* beta_1: Exponential decay of the rate for the first moment estimates. - - * Default: 0.9 - -* beta_2: Exponential decay rate for the second-moment estimates. - - * Default: 0.999 - -* alpha: Step size. - - * Default: 0.5 - -* epsilon: A small value to prevent zero-division. - - * Default: 10^(-8) - -* sensitivity: shrinking scale for VarBds - - * Default: 10^(-7) - - -References: -=========== -This solver is adapted from the article Kingma, D. P., & Ba, J. (2014). Adam: A method for stochastic optimization. arXiv preprint arXiv:1412.6980. +Solver: ADAM +============ + +Description: +------------ +The solver is for efficient stochastic optimization that only requires first-order gradients +with little memory requirement. The method computes individual adaptive learning rates for +different parameters from estimates of first and second moments of the gradients. + + +Modifications & Implementation: +------------------------------- +At each timestep :math:`t`, we first evaluate the gradient w.r.t the current solution :math:`x`, either using +the IPA gradient estimates or finite difference estimates. +Then, the algorithm updates exponential moving averages of the gradient :math:`m_t` and the squared gradient +:math:`v_t` where the hyper-parameters :math:`\beta_1` and :math:`\beta_2` control the exponential decay rates of +these moving averages. The moving averages themselves are estimates of the 1st moment (the mean) and the +2nd raw moment (the uncentered variance) of the gradient. These moving averages are +initialized as (vectors of) 0's, leading to moment estimates that are biased towards zero, especially +during the initial timesteps, and especially when the decay rates are small (i.e., the :math:`\beta` are close to 1). +The bias-corrected estimates :math:`\hat{m_t}` and :math:`\hat{v_t}`. Lastly, the new solution can be found via +current solution, the bias-corrected first and second moment estimate, and the step size. + +Helper functions: +The finite_diff function uses finite difference methods to estimate the gradient of the +objective function. + + +Scope: +------ +* objective_type: single + +* constraint_type: box + +* variable_type: continuous + + +Solver Factors: +--------------- +* crn_across_solns: Use CRN across solutions? + + * Default: True + +* r: Number of replications taken at each solution. + + * Default: 30 + +* beta_1: Exponential decay of the rate for the first moment estimates. + + * Default: 0.9 + +* beta_2: Exponential decay rate for the second-moment estimates. + + * Default: 0.999 + +* alpha: Step size. + + * Default: 0.5 + +* epsilon: A small value to prevent zero-division. + + * Default: 10^(-8) + +* sensitivity: shrinking scale for VarBds + + * Default: 10^(-7) + + +References: +=========== +This solver is adapted from the article Kingma, D. P., & Ba, J. (2014). Adam: A method for stochastic optimization. arXiv preprint arXiv:1412.6980. diff --git a/docs/aloe.rst b/docs/source/aloe.rst similarity index 96% rename from docs/aloe.rst rename to docs/source/aloe.rst index e46dc0a28..64bd9b901 100644 --- a/docs/aloe.rst +++ b/docs/source/aloe.rst @@ -1,75 +1,75 @@ -Solver: Adaptive Line-search with Oracle Estimations (ALOE) -=========================================================== - -Description: ------------- -The solver is a stochastic line search algorithm with the gradient estimate recomputed in each iteration, -whether or not a step is accepted. The algorithm includes the relaxation of the Armijo condition by -an additive constant :math:`2\epsilon_f`. - - -Modifications & Implementation: -------------------------------- -For each iteration, first compute the gradient approximation :math:`g_k` using either -the IPA gradient estimates or finite difference estimates. -Then, the algorithm checks for sufficient decrease. Let :math:`x_k^{+} = x_k - \alpha_k g_k`. Estimate the objective -values :math:`f(x_k^{+})` and :math:`f(x_k)`. Check the modified Arimjo condition: - -.. math:: - - f(x_k^{+}) \leq f(x_k) - \alpha_k \theta ||g_k||^2 + 2\epsilon_f. - -If the condition holds, then set :math:`x_{k+1} \leftarrow x_{k}` and :math:`\alpha_{k+1} \leftarrow \min\{ \alpha_{max}, \gamma^{-1}\alpha_k \}`. -Otherwise, set :math:`x_{k+1} \leftarrow x_{k}` and :math:`\alpha_{k+1} \leftarrow \gamma \alpha_k` - -Helper functions: -The finite_diff function uses finite difference methods to estimate the gradient of the objective function. - - -Scope: ------- -* objective_type: single - -* constraint_type: box - -* variable_type: continuous - - -Solver Factors: ---------------- -* crn_across_solns: Use CRN across solutions? - - * Default: True - -* r: Number of replications taken at each solution. - - * Default: 30 - -* theta: Constant in the Armijo condition. - - * Default: 0.2 - -* gamma: Constant for shrinking the step size. - - * Default: 0.8 - -* alpha_max: Maximum step size. - - * Default: 10 - -* alpha_0: Initial step size. - - * Default: 1 - -* epsilon_f: Additive constant in the Armijo condition. - - * Default: 1 - -* sensitivity: Shrinking scale for variable bounds. - - * Default: 10^(-7) - - -References: -=========== -This solver is adapted from the article Jin, B., Scheinberg, K., & Xie, M. (2021). High probability complexity bounds for line search based on stochastic oracles. Advances in Neural Information Processing Systems, 34, 9193-9203. +Solver: Adaptive Line-search with Oracle Estimations (ALOE) +=========================================================== + +Description: +------------ +The solver is a stochastic line search algorithm with the gradient estimate recomputed in each iteration, +whether or not a step is accepted. The algorithm includes the relaxation of the Armijo condition by +an additive constant :math:`2\epsilon_f`. + + +Modifications & Implementation: +------------------------------- +For each iteration, first compute the gradient approximation :math:`g_k` using either +the IPA gradient estimates or finite difference estimates. +Then, the algorithm checks for sufficient decrease. Let :math:`x_k^{+} = x_k - \alpha_k g_k`. Estimate the objective +values :math:`f(x_k^{+})` and :math:`f(x_k)`. Check the modified Arimjo condition: + +.. math:: + + f(x_k^{+}) \leq f(x_k) - \alpha_k \theta ||g_k||^2 + 2\epsilon_f. + +If the condition holds, then set :math:`x_{k+1} \leftarrow x_{k}` and :math:`\alpha_{k+1} \leftarrow \min\{ \alpha_{max}, \gamma^{-1}\alpha_k \}`. +Otherwise, set :math:`x_{k+1} \leftarrow x_{k}` and :math:`\alpha_{k+1} \leftarrow \gamma \alpha_k` + +Helper functions: +The finite_diff function uses finite difference methods to estimate the gradient of the objective function. + + +Scope: +------ +* objective_type: single + +* constraint_type: box + +* variable_type: continuous + + +Solver Factors: +--------------- +* crn_across_solns: Use CRN across solutions? + + * Default: True + +* r: Number of replications taken at each solution. + + * Default: 30 + +* theta: Constant in the Armijo condition. + + * Default: 0.2 + +* gamma: Constant for shrinking the step size. + + * Default: 0.8 + +* alpha_max: Maximum step size. + + * Default: 10 + +* alpha_0: Initial step size. + + * Default: 1 + +* epsilon_f: Additive constant in the Armijo condition. + + * Default: 1 + +* sensitivity: Shrinking scale for variable bounds. + + * Default: 10^(-7) + + +References: +=========== +This solver is adapted from the article Jin, B., Scheinberg, K., & Xie, M. (2021). High probability complexity bounds for line search based on stochastic oracles. Advances in Neural Information Processing Systems, 34, 9193-9203. diff --git a/docs/amusementpark.rst b/docs/source/amusementpark.rst similarity index 97% rename from docs/amusementpark.rst rename to docs/source/amusementpark.rst index 6ccdacd56..c43f40252 100644 --- a/docs/amusementpark.rst +++ b/docs/source/amusementpark.rst @@ -1,153 +1,153 @@ -Model: Amusement Park Queues (AMUSEMENT) -========================================== - -Description: ------------- -This model simulates an amusement park with 7 attractions. Visitors arrive at -each attraction according to a poisson distribution with a rate :math:`\gamma_i = 1`, -:math:`i = 1,. . . , 7`. Each attraction can only take one visitor at a time, while -others wait in a queue with capacity :math:`c_i`. If a visitor finds a queue full, -they will immediately leave the park. - -After visiting each attraction, a visitor leaves the park with probability 0.2. -Otherwise, the visitor goes to another attraction according to the transition -matrix: - -.. image:: amusementpark.png - :alt: The transition matrix has failed to display - :width: 700 - -The time that a visitor spends at an attraction follows an Erlang -distribution with shape parameter :math:`k = 2`` and rate :math:`\lambda = 9`. -The park opens at 9AM and closes at 5PM, and time is measured in minutes. -When the park closes, all visitors in the queue leave immediately. - -Sources of Randomness: ----------------------- -There are 3 sources of randomness in this model: - -* The arrival rate of visitors as a poisson distribution with rate of 1 for all :math:`i = 1, . . . , 7`. - -* The transition probabiliyt matrix that visitors follow after visiting each attraction. - -* The time spent at each attraction as an Erlang distribution with the shape parameter :math:`k = 2` and rate = 9. - -The Erlang distribution is the distribution representing a sum of :math:`k` independent exponential variables with mean :math:`1/\lambda` each. -It is a special case of the gamma distribution wherein the shape of the distribution is discretized. The probability density function -of the Erlang distribution is - -:math:`f(x;k,\lambda) = \frac{\lambda^{k}x^{k-1}e^{-\lambda x}}{(k-1)!} \quad for \ x, \beta >= 0` - -where :math:`k` is the shape parameter, :math:`\lambda` is the rate parameter. - -Alternatively, the pdf can be expressed as - -:math:`f(x;k,\beta) = \frac{x^{k-1}e^{-x/\beta}}{\beta^k(k-1)!} \quad for \ x, \beta >= 0` - -where :math:`\beta` is the scale parameter, which is the reciprocal of the rate parameter. - -* Note: In this model, Erlang variates are generated through the gamma distribution with the scale (:math:`\beta:`) parameter set to 1/9. -Accordingly, the reciprocal of desired rate values should be used in the erlang_scale parameter. - - -Model Factors: --------------- -* park_capacity: The total number of visitors waiting for attractions that can be maintained through park facilities, distributed across the attractions. - - * Default: 350 - -* number_attractions: The number of attractions in the park. - - * Default: 7 - -* time_open: The number of minutes per day the park is open. - - * Default: 480 - -* erlang_shape: The shape parameter of the Erlang distribution for each attraction duration. - - * Default: [2, 2, 2, 2, 2, 2, 2] - -* erlang_scale: The scale parameter of the Erlang distribution for each attraction duration (reciprocal of the rate value). - - * Default: [1/9, 1/9, 1/9, 1/9, 1/9, 1/9, 1/9] - -* depart_probabilities: The probability that a visitor will depart the park after visiting an attraction. - - * Default: [0.2, 0.2, 0.2, 0.2, 0.2, 0.2, 0.2] - -* queue_capacities: The capacity of the queues for the attractions based on the portion of facilities allocated. - - * Default: [50, 50, 50, 50, 50, 50, 50] - -* arrival_gammas: The gamma values for the poisson distributions dictating the rates at which visitors entering the park arrive at each attraction. - - * Default: [1, 1, 1, 1, 1, 1, 1] - -* transition_probabilities: The transition matrix that describes the probability of a visitor visiting each attraction after their current attraction. - - * Default: - .. image:: amusementpark.png - :alt: The transition matrix has failed to display - :width: 700 - -Responses: ----------- -* total_departed: The total number of visitors to leave the park due to full queues. - -* percent_departed: The percentage of visitors to leave the park due to full queues. - -* average_number_in_system: The time average of the number of visitors in the system. - -* attraction_utilization_percentages: The percent utilizations for each attraction. - -References: -=========== -This model is adapted from the article: -Vill’en-Altamirano, J. (2009). Restart Simulation of Networks of Queues with -Erlang Service Times. *Proceedings of the 2009 Winter Simulation Conference.* - -Optimization Problem: Minimize Total Departed Visitors (AMUSEMENT-1) -==================================================================== - -Decision Variables: -------------------- -* queue_capacities - -Objectives: ------------ -Minimize total number of departed visitors. - -Constraints: ------------- -* park_capacity = 350 - -* :math:`\sum_{i=1}^{7}` queue_capacities = park_capacity - -* queue_capacities :math:`\ge` 0 - -Problem Factors: ----------------- -* Budget: Max # of replications for a solver to take. - - * Default: 1000 - -Fixed Model Factors: --------------------- -* N/A - -Starting Solution: ------------------- -* queue_capacities = [50, 50, 50, 50, 50, 50, 50] - -Random Solutions: ------------------- -Generate a solution uniformly from a space of vectors of length 7 that sum up to 350. - -Optimal Solution: ------------------ -unknown - -Optimal Objective Function Value: ---------------------------------- -unknown +Model: Amusement Park Queues (AMUSEMENT) +========================================== + +Description: +------------ +This model simulates an amusement park with 7 attractions. Visitors arrive at +each attraction according to a poisson distribution with a rate :math:`\gamma_i = 1`, +:math:`i = 1,. . . , 7`. Each attraction can only take one visitor at a time, while +others wait in a queue with capacity :math:`c_i`. If a visitor finds a queue full, +they will immediately leave the park. + +After visiting each attraction, a visitor leaves the park with probability 0.2. +Otherwise, the visitor goes to another attraction according to the transition +matrix: + +.. image:: amusementpark.png + :alt: The transition matrix has failed to display + :width: 700 + +The time that a visitor spends at an attraction follows an Erlang +distribution with shape parameter :math:`k = 2`` and rate :math:`\lambda = 9`. +The park opens at 9AM and closes at 5PM, and time is measured in minutes. +When the park closes, all visitors in the queue leave immediately. + +Sources of Randomness: +---------------------- +There are 3 sources of randomness in this model: + +* The arrival rate of visitors as a poisson distribution with rate of 1 for all :math:`i = 1, . . . , 7`. + +* The transition probabiliyt matrix that visitors follow after visiting each attraction. + +* The time spent at each attraction as an Erlang distribution with the shape parameter :math:`k = 2` and rate = 9. + +The Erlang distribution is the distribution representing a sum of :math:`k` independent exponential variables with mean :math:`1/\lambda` each. +It is a special case of the gamma distribution wherein the shape of the distribution is discretized. The probability density function +of the Erlang distribution is + +:math:`f(x;k,\lambda) = \frac{\lambda^{k}x^{k-1}e^{-\lambda x}}{(k-1)!} \quad for \ x, \beta >= 0` + +where :math:`k` is the shape parameter, :math:`\lambda` is the rate parameter. + +Alternatively, the pdf can be expressed as + +:math:`f(x;k,\beta) = \frac{x^{k-1}e^{-x/\beta}}{\beta^k(k-1)!} \quad for \ x, \beta >= 0` + +where :math:`\beta` is the scale parameter, which is the reciprocal of the rate parameter. + +* Note: In this model, Erlang variates are generated through the gamma distribution with the scale (:math:`\beta:`) parameter set to 1/9. +Accordingly, the reciprocal of desired rate values should be used in the erlang_scale parameter. + + +Model Factors: +-------------- +* park_capacity: The total number of visitors waiting for attractions that can be maintained through park facilities, distributed across the attractions. + + * Default: 350 + +* number_attractions: The number of attractions in the park. + + * Default: 7 + +* time_open: The number of minutes per day the park is open. + + * Default: 480 + +* erlang_shape: The shape parameter of the Erlang distribution for each attraction duration. + + * Default: [2, 2, 2, 2, 2, 2, 2] + +* erlang_scale: The scale parameter of the Erlang distribution for each attraction duration (reciprocal of the rate value). + + * Default: [1/9, 1/9, 1/9, 1/9, 1/9, 1/9, 1/9] + +* depart_probabilities: The probability that a visitor will depart the park after visiting an attraction. + + * Default: [0.2, 0.2, 0.2, 0.2, 0.2, 0.2, 0.2] + +* queue_capacities: The capacity of the queues for the attractions based on the portion of facilities allocated. + + * Default: [50, 50, 50, 50, 50, 50, 50] + +* arrival_gammas: The gamma values for the poisson distributions dictating the rates at which visitors entering the park arrive at each attraction. + + * Default: [1, 1, 1, 1, 1, 1, 1] + +* transition_probabilities: The transition matrix that describes the probability of a visitor visiting each attraction after their current attraction. + + * Default: + .. image:: amusementpark.png + :alt: The transition matrix has failed to display + :width: 700 + +Responses: +---------- +* total_departed: The total number of visitors to leave the park due to full queues. + +* percent_departed: The percentage of visitors to leave the park due to full queues. + +* average_number_in_system: The time average of the number of visitors in the system. + +* attraction_utilization_percentages: The percent utilizations for each attraction. + +References: +=========== +This model is adapted from the article: +Vill’en-Altamirano, J. (2009). Restart Simulation of Networks of Queues with +Erlang Service Times. *Proceedings of the 2009 Winter Simulation Conference.* + +Optimization Problem: Minimize Total Departed Visitors (AMUSEMENT-1) +==================================================================== + +Decision Variables: +------------------- +* queue_capacities + +Objectives: +----------- +Minimize total number of departed visitors. + +Constraints: +------------ +* park_capacity = 350 + +* :math:`\sum_{i=1}^{7}` queue_capacities = park_capacity + +* queue_capacities :math:`\ge` 0 + +Problem Factors: +---------------- +* Budget: Max # of replications for a solver to take. + + * Default: 1000 + +Fixed Model Factors: +-------------------- +* N/A + +Starting Solution: +------------------ +* queue_capacities = [50, 50, 50, 50, 50, 50, 50] + +Random Solutions: +------------------ +Generate a solution uniformly from a space of vectors of length 7 that sum up to 350. + +Optimal Solution: +----------------- +unknown + +Optimal Objective Function Value: +--------------------------------- +unknown diff --git a/docs/astrodf.rst b/docs/source/astrodf.rst similarity index 97% rename from docs/astrodf.rst rename to docs/source/astrodf.rst index 0406b571b..2474e22ed 100644 --- a/docs/astrodf.rst +++ b/docs/source/astrodf.rst @@ -1,83 +1,83 @@ -Solver: Adaptive Sampling Trust-Region Optimization for Derivative-Free Simulations (ASTRODF) -============================================================================================= - -Description: ------------- -The solver progressively builds local models (quadratic with diagonal Hessian) using interpolation on a set of points on the coordinate bases of the best (incumbent) solution. Solving the local models within a trust region (closed ball around the incumbent solution) at each iteration suggests a candidate solution for the next iteration. If the candidate solution is worse than the best interpolation point, it is replaced with the latter (a.k.a. direct search). The solver then decides whether to accept the candidate solution and expand the trust-region or reject it and shrink the trust-region based on a success ratio test. The sample size at each visited point is determined adaptively and based on closeness to optimality. - -Modifications & Implementation: -------------------------------- - -**construct_model**: Construct the "qualified" local model for each iteration k with the center point x_k, reconstruct with new points in a shrunk trust-region if the model fails the criticality condition. The criticality condition keeps the model gradient norm and the trust-region size in lock-step. - -**evaluate_model**: Find (proxy to) the subproblem solution. - -**get_stopping_time**: Decide whether to stop at the existing sample size for a given solution. - -**get_coordinate_vector**: Form the coordinate basis. - -**get_rotated_basis**: Form the rotated coordinates, where the first vector comes from the visited design points. - -**get_model_coefficients**: Compute the model coefficients using (2d+1) design points and their function estimates by solving a system of linear equations (interpolation). - -**get_coordinate_basis_interpolation_points**: Compute the interpolation points (2d+1) using the coordinate basis. - -**get_rotated_basis_interpolation_points**: Compute the interpolation points (2d+1) using the rotated coordinate basis to allow reusing one design point. - -**iterate**: Run one iteration of trust-region algorithm by bulding and solving a local model and updating the current incumbent and trust-region radius, and saving the data. - -Scope: ------- -* objective_type: single - -* constraint_type: box - -* variable_type: continuous - -* gradient_observations: not available - -Solver Factors: ---------------- -* crn_across_solns: Use CRN across solutions? - - * Default: True - -* eta_1: Threshhold for a successful iteration > 0, < 1. - - * Default: 0.1 - -* eta_2: Threshhold for a very successful iteration > eta_1, < 1. - - * Default: 0.8 - -* gamma_1: Trust-region radius increase rate after a very successful iteration > 1. - - * Default: 1.5 - -* gamma_2: Trust-region radius decrease rate after an unsuccessful iteration < 1, > 0. - - * Default: 0.5 - -* lambda_min: Minimum sample size value, integer > 2. - - * Default: 4 - -* seasy_solve: Solve the subproblem approximately with Cauchy point. - - * Default: True - -* reuse_points: Reuse the previously visited points. - - * Default: True - -* ps_sufficient_reduction: Use pattern search if with sufficient reduction, 0 always allows it, large value never does. - - * Default: 0.1 - - -References: -=========== -This solver is adapted from the article Ha, Y., Shashaani, S., and Tran-Dinh, Q. (2021). -Improved Complexity Of Trust-Region Optimization For Zeroth-Order Stochastic Oracles with Adaptive Sampling -*Proceedings of 2021 Winter Simulation Conference*, doi: 10.1109/WSC52266.2021.9715529. +Solver: Adaptive Sampling Trust-Region Optimization for Derivative-Free Simulations (ASTRODF) +============================================================================================= + +Description: +------------ +The solver progressively builds local models (quadratic with diagonal Hessian) using interpolation on a set of points on the coordinate bases of the best (incumbent) solution. Solving the local models within a trust region (closed ball around the incumbent solution) at each iteration suggests a candidate solution for the next iteration. If the candidate solution is worse than the best interpolation point, it is replaced with the latter (a.k.a. direct search). The solver then decides whether to accept the candidate solution and expand the trust-region or reject it and shrink the trust-region based on a success ratio test. The sample size at each visited point is determined adaptively and based on closeness to optimality. + +Modifications & Implementation: +------------------------------- + +**construct_model**: Construct the "qualified" local model for each iteration k with the center point x_k, reconstruct with new points in a shrunk trust-region if the model fails the criticality condition. The criticality condition keeps the model gradient norm and the trust-region size in lock-step. + +**evaluate_model**: Find (proxy to) the subproblem solution. + +**get_stopping_time**: Decide whether to stop at the existing sample size for a given solution. + +**get_coordinate_vector**: Form the coordinate basis. + +**get_rotated_basis**: Form the rotated coordinates, where the first vector comes from the visited design points. + +**get_model_coefficients**: Compute the model coefficients using (2d+1) design points and their function estimates by solving a system of linear equations (interpolation). + +**get_coordinate_basis_interpolation_points**: Compute the interpolation points (2d+1) using the coordinate basis. + +**get_rotated_basis_interpolation_points**: Compute the interpolation points (2d+1) using the rotated coordinate basis to allow reusing one design point. + +**iterate**: Run one iteration of trust-region algorithm by bulding and solving a local model and updating the current incumbent and trust-region radius, and saving the data. + +Scope: +------ +* objective_type: single + +* constraint_type: box + +* variable_type: continuous + +* gradient_observations: not available + +Solver Factors: +--------------- +* crn_across_solns: Use CRN across solutions? + + * Default: True + +* eta_1: Threshhold for a successful iteration > 0, < 1. + + * Default: 0.1 + +* eta_2: Threshhold for a very successful iteration > eta_1, < 1. + + * Default: 0.8 + +* gamma_1: Trust-region radius increase rate after a very successful iteration > 1. + + * Default: 1.5 + +* gamma_2: Trust-region radius decrease rate after an unsuccessful iteration < 1, > 0. + + * Default: 0.5 + +* lambda_min: Minimum sample size value, integer > 2. + + * Default: 4 + +* seasy_solve: Solve the subproblem approximately with Cauchy point. + + * Default: True + +* reuse_points: Reuse the previously visited points. + + * Default: True + +* ps_sufficient_reduction: Use pattern search if with sufficient reduction, 0 always allows it, large value never does. + + * Default: 0.1 + + +References: +=========== +This solver is adapted from the article Ha, Y., Shashaani, S., and Tran-Dinh, Q. (2021). +Improved Complexity Of Trust-Region Optimization For Zeroth-Order Stochastic Oracles with Adaptive Sampling +*Proceedings of 2021 Winter Simulation Conference*, doi: 10.1109/WSC52266.2021.9715529. (https://ieeexplore.ieee.org/abstract/document/9715529) \ No newline at end of file diff --git a/docs/base.rst b/docs/source/base.rst similarity index 93% rename from docs/base.rst rename to docs/source/base.rst index 38206cd9f..81e4b172d 100644 --- a/docs/base.rst +++ b/docs/source/base.rst @@ -1,7 +1,7 @@ -base module -=========== - -.. automodule:: base - :members: - :undoc-members: - :show-inheritance: +base module +=========== + +.. automodule:: base + :members: + :undoc-members: + :show-inheritance: diff --git a/docs/chessmm.rst b/docs/source/chessmm.rst similarity index 96% rename from docs/chessmm.rst rename to docs/source/chessmm.rst index bc2a40b5e..0a0ed2b75 100644 --- a/docs/chessmm.rst +++ b/docs/source/chessmm.rst @@ -1,108 +1,108 @@ -Model: Chess Matchmaking Optimization (CHESS) -============================================= - -Description: ------------- -Chess players are rated using the Elo rating system, which assigns a (non-unique) -number to each player based on their level of skill. The model simulates an online -chess-matchmaking platform, which tries to match players of similar skill level. - -The platform uses a search width :math:`x`, which is the maximum allowable difference -in Elo rating between two matched players. :math:`N` players are drawn from a distribution -of Elo ratings and arrive (independent of their rating) according to a stationary -Poisson process with rate :math:`\lambda`. When a player arrives, and there is an existing, -unmatched player with Elo rating within :math:`x` of the first player's Elo rating, they -are matched. If not, then the player waits for an opponent with an appropriate Elo -rating to arrive. - -Sources of Randomness: ----------------------- -1. To create the Elo distribution, first generate a normal distribution with mean -:math:`1200` and standard deviation :math:`\frac{1200}{\sqrt(2)*\text{erfcinv}(\frac{1}{50})}`, -where erfcinv is the inverse complementary error function. This results in a distribution -where the 1st percentile is at :math:`0`, and the 99th percentile is at :math:`2400`. -Next, truncate the distribution at :math:`0` and :math:`2400`. -2. A stationary Poisson process with rate :math:`\lambda` for arrivals. - -Model Factors: --------------- -* elo_mean: Mean of normal distribution for Elo rating. - - * Default: 1200.0 - -* elo_sd: Standard deviation of normal distribution for Elo rating. - - * Default: 1200 / (np.sqrt(2) * special.erfcinv(1 / 50)) - -* poisson_rate: Rate of Poisson process for player arrivals. - - * Default: 1.0 - -* num_players: Number of players. - - * Default: 1000 - -* allowable_diff: Maximum allowable difference between Elo ratings. - - * Default: 150.0 - -Responses: ----------- -* avg_diff: The average Elo difference between all pairs. - -* avg_wait_time: The average waiting time. - -References: -=========== -Original author of this problem is Bryan Chong (March 15, 2015). - - - - -Optimization Problem: Minimize Average Elo Difference (CHESS-1) -=============================================================== - -Decision Variables: -------------------- -* allowable_diff - -Objectives: ------------ -Minimize the average Elo difference between all pairs of matched players. - -Constraints: ------------- -Maximum allowable difference is between 0 and 2400. - -The average waiting time is :math:`\leq \delta`. - -Problem Factors: ----------------- -* budget: Max # of replications for a solver to take. - - * Default: 1000 - -* upper_time: Upper bound on wait time. - - * Default: 5.0 - -Fixed Model Factors: --------------------- -* N/A - -Starting Solution: ------------------- -* initial_solution: (150,) - -Random Solutions: ------------------ -First draw :math:`x` from a normal distribution with mean :math:`150` and standard -deviation :math:`50`, then set :math:`x = \min(\max(x, 0), 2400)`. - -Optimal Solution: ------------------ -Unknown - -Optimal Objective Function Value: ---------------------------------- +Model: Chess Matchmaking Optimization (CHESS) +============================================= + +Description: +------------ +Chess players are rated using the Elo rating system, which assigns a (non-unique) +number to each player based on their level of skill. The model simulates an online +chess-matchmaking platform, which tries to match players of similar skill level. + +The platform uses a search width :math:`x`, which is the maximum allowable difference +in Elo rating between two matched players. :math:`N` players are drawn from a distribution +of Elo ratings and arrive (independent of their rating) according to a stationary +Poisson process with rate :math:`\lambda`. When a player arrives, and there is an existing, +unmatched player with Elo rating within :math:`x` of the first player's Elo rating, they +are matched. If not, then the player waits for an opponent with an appropriate Elo +rating to arrive. + +Sources of Randomness: +---------------------- +1. To create the Elo distribution, first generate a normal distribution with mean +:math:`1200` and standard deviation :math:`\frac{1200}{\sqrt(2)*\text{erfcinv}(\frac{1}{50})}`, +where erfcinv is the inverse complementary error function. This results in a distribution +where the 1st percentile is at :math:`0`, and the 99th percentile is at :math:`2400`. +Next, truncate the distribution at :math:`0` and :math:`2400`. +2. A stationary Poisson process with rate :math:`\lambda` for arrivals. + +Model Factors: +-------------- +* elo_mean: Mean of normal distribution for Elo rating. + + * Default: 1200.0 + +* elo_sd: Standard deviation of normal distribution for Elo rating. + + * Default: 1200 / (np.sqrt(2) * special.erfcinv(1 / 50)) + +* poisson_rate: Rate of Poisson process for player arrivals. + + * Default: 1.0 + +* num_players: Number of players. + + * Default: 1000 + +* allowable_diff: Maximum allowable difference between Elo ratings. + + * Default: 150.0 + +Responses: +---------- +* avg_diff: The average Elo difference between all pairs. + +* avg_wait_time: The average waiting time. + +References: +=========== +Original author of this problem is Bryan Chong (March 15, 2015). + + + + +Optimization Problem: Minimize Average Elo Difference (CHESS-1) +=============================================================== + +Decision Variables: +------------------- +* allowable_diff + +Objectives: +----------- +Minimize the average Elo difference between all pairs of matched players. + +Constraints: +------------ +Maximum allowable difference is between 0 and 2400. + +The average waiting time is :math:`\leq \delta`. + +Problem Factors: +---------------- +* budget: Max # of replications for a solver to take. + + * Default: 1000 + +* upper_time: Upper bound on wait time. + + * Default: 5.0 + +Fixed Model Factors: +-------------------- +* N/A + +Starting Solution: +------------------ +* initial_solution: (150,) + +Random Solutions: +----------------- +First draw :math:`x` from a normal distribution with mean :math:`150` and standard +deviation :math:`50`, then set :math:`x = \min(\max(x, 0), 2400)`. + +Optimal Solution: +----------------- +Unknown + +Optimal Objective Function Value: +--------------------------------- Unknown \ No newline at end of file diff --git a/docs/cntnv.rst b/docs/source/cntnv.rst similarity index 96% rename from docs/cntnv.rst rename to docs/source/cntnv.rst index 8fb8f3931..d84491a07 100644 --- a/docs/cntnv.rst +++ b/docs/source/cntnv.rst @@ -1,111 +1,111 @@ - -Model: Continuous Newsvendor Problem (CNTNV) -============================================ - -Description: ------------- - -A vendor orders a fixed quantity of liquid at the beginning of a day to be -sold to customers throughout the day. The vendor pays a per-unit order cost -:math:`c` for the initial inventory and sells it the product to customers at a per-unit price -:math:`s`. At the end of the day, any unsold liquid can be salvaged at a per-unit price, :math:`w`. - -Sources of Randomness: ----------------------- - -Each day's random demand for liquid product follows Burr Type XII distribution and is denoted by :math:`D`. -The parameters of the Burr Type XII distribution are :math:`α` and :math:`β` so that its cumulative -distribution function is given by :math:`F(x) = 1 - (1+x^α)^{-β}` where :math:`x, α,` and -:math:`β` are all positive. - -Model Factors: --------------- - -* Cost (:math:`c`): The price at which the newsvendor purchases one unit volume of liquid. - - * Default: 5 - -* Price (:math:`s`): The price at which the newsvendor sells one unit volume of liquid. - - * Default: 9 - -* Salvage Price (:math:`w`): The price at which any unsold liquid is sold for salvage. - - * Default: 1 - -* Alpha (:math:`α`): Parameter for the demand distribution. - - * Default: 2 - -* Beta (:math:`β`): Parameter for the demand distribution. - - * Default: 20 - -* Quantity of Liquid (:math:`x`): Amount (volume) of liquid ordered at the beginning of the day. - - * Default: 0.5 - -Responses: ----------- - -* Profit: The daily profit; can be negative if a loss is incurred. - -References: -=========== - -Evan L. Porteus. Stochastic inventory theory. In D. P. Heyman and M. J. Sobel, editors, -Stochastic Models, volume 2 of Handbooks in Operations Research and Management Science, -chapter 12, pages 605–652. Elsevier, New York, 1990. - - -Optimization Problem: Maximize Profit -===================================== - -Decision Variables: -------------------- - -* Quantity of Liquid (:math:`x`): Amount (volume) of liquid ordered at the beginning of the day. - -Objectives: ------------ - -Maximizes the vendor's expected profit. - -Constraints: ------------- - -Quantity of Liquid must be non-negative: :math:`x > 0` - -Problem Factors: ----------------- - -* Budget: Max # of replications for a solver to take. - - * Default: 1000 - -Fixed Model Factors: --------------------- - -* N/A - -Starting Solution: ------------------- - -* :math:`x = 0` - - -Random Solutions: ------------------ - -If random solutions are needed, generate :math:`x` from an Exponential distribution with mean 1. - -Optimal Solution: ------------------ - -Global minimum at :math:`x^* = (1/((1-r)^{1/β})-1)^{1/α}`. -For the default factors, the optimal solution is :math:`x^*` = 0.1878. - -Optimal Objective Function Value: ---------------------------------- - -For the default factors, the maximum expected profit is 0.4635. + +Model: Continuous Newsvendor Problem (CNTNV) +============================================ + +Description: +------------ + +A vendor orders a fixed quantity of liquid at the beginning of a day to be +sold to customers throughout the day. The vendor pays a per-unit order cost +:math:`c` for the initial inventory and sells it the product to customers at a per-unit price +:math:`s`. At the end of the day, any unsold liquid can be salvaged at a per-unit price, :math:`w`. + +Sources of Randomness: +---------------------- + +Each day's random demand for liquid product follows Burr Type XII distribution and is denoted by :math:`D`. +The parameters of the Burr Type XII distribution are :math:`α` and :math:`β` so that its cumulative +distribution function is given by :math:`F(x) = 1 - (1+x^α)^{-β}` where :math:`x, α,` and +:math:`β` are all positive. + +Model Factors: +-------------- + +* Cost (:math:`c`): The price at which the newsvendor purchases one unit volume of liquid. + + * Default: 5 + +* Price (:math:`s`): The price at which the newsvendor sells one unit volume of liquid. + + * Default: 9 + +* Salvage Price (:math:`w`): The price at which any unsold liquid is sold for salvage. + + * Default: 1 + +* Alpha (:math:`α`): Parameter for the demand distribution. + + * Default: 2 + +* Beta (:math:`β`): Parameter for the demand distribution. + + * Default: 20 + +* Quantity of Liquid (:math:`x`): Amount (volume) of liquid ordered at the beginning of the day. + + * Default: 0.5 + +Responses: +---------- + +* Profit: The daily profit; can be negative if a loss is incurred. + +References: +=========== + +Evan L. Porteus. Stochastic inventory theory. In D. P. Heyman and M. J. Sobel, editors, +Stochastic Models, volume 2 of Handbooks in Operations Research and Management Science, +chapter 12, pages 605–652. Elsevier, New York, 1990. + + +Optimization Problem: Maximize Profit +===================================== + +Decision Variables: +------------------- + +* Quantity of Liquid (:math:`x`): Amount (volume) of liquid ordered at the beginning of the day. + +Objectives: +----------- + +Maximizes the vendor's expected profit. + +Constraints: +------------ + +Quantity of Liquid must be non-negative: :math:`x > 0` + +Problem Factors: +---------------- + +* Budget: Max # of replications for a solver to take. + + * Default: 1000 + +Fixed Model Factors: +-------------------- + +* N/A + +Starting Solution: +------------------ + +* :math:`x = 0` + + +Random Solutions: +----------------- + +If random solutions are needed, generate :math:`x` from an Exponential distribution with mean 1. + +Optimal Solution: +----------------- + +Global minimum at :math:`x^* = (1/((1-r)^{1/β})-1)^{1/α}`. +For the default factors, the optimal solution is :math:`x^*` = 0.1878. + +Optimal Objective Function Value: +--------------------------------- + +For the default factors, the maximum expected profit is 0.4635. diff --git a/docs/conf.py b/docs/source/conf.py similarity index 96% rename from docs/conf.py rename to docs/source/conf.py index dc15780c8..2c3e6641b 100644 --- a/docs/conf.py +++ b/docs/source/conf.py @@ -25,15 +25,14 @@ sys.path.insert(0, os.path.abspath("../simopt")) sys.path.insert(0, os.path.abspath("..")) - # -- Project information ----------------------------------------------------- project = "SimOpt" -copyright = "2021, simopt-admin" # noqa: A001 +copyright = "2025, simopt-admin" # noqa: A001 author = "simopt-admin" # The full version, including alpha/beta/rc tags -release = "1.0" +release = "1.1.1" # -- General configuration --------------------------------------------------- @@ -90,8 +89,7 @@ # relative to this directory. They are copied after the builtin static files, # so a file named "default.css" will overwrite the builtin "default.css". -# html_static_path = ['_static'] -html_static_path = [] +html_static_path = ['_static'] main(["-o", os.path.abspath("."), os.path.abspath(".."), "-f"]) diff --git a/docs/contam.rst b/docs/source/contam.rst similarity index 96% rename from docs/contam.rst rename to docs/source/contam.rst index c44ba7f56..028fb097a 100644 --- a/docs/contam.rst +++ b/docs/source/contam.rst @@ -1,188 +1,188 @@ -Model: Contamination Control Problem (CONTAM) -============================================= - -Description: ------------- -Consider a food supply chain consisting of :math:`n` stages. Pathogenic microorganisms -and other poisonous elements can contaminate some fraction of the food supply at each -stage. Specifically, let the growth rate of contamination at stage :math:`i` of the -chain be denoted by the random variable :math:`\Lambda_i`, :math:`0 \leq \Lambda_i \leq 1` -for :math:`i = 1, 2, ..., n`. If a prevention effort is made at stage :math:`i`, -the contamination decreases by the random rate :math:`\Gamma_i`, :math:`0 \leq \Gamma_i \leq 1` -with associated prevention cost :math:`c_i`. Let the binary variable :math:`u_i` represent -whether a prevention measure is executed at stage :math:`i`. - - -Sources of Randomness: ----------------------- -1. Contamination rate :math:`\Lambda_i ~ Beta(1, \frac{17}{3})` for :math:`i = 1, 2, ..., n`; -2. Restoration rate :math:`\Gamma_i ~ Beta(1, \frac{3}{7})` for :math:`i = 1, 2, ..., n`; - -Model Factors: --------------- -* contam_rate_alpha: Alpha parameter of beta distribution for growth rate of contamination at each stage. - - * Default: 1.0 - -* contam_rate_beta: Beta parameter of beta distribution for growth rate of contamination at each stage. - - * Default: 17/3 - -* restore_rate_alpha: Alpha parameter of beta distribution for rate that contamination decreases by after prevention effort. - - * Default: 1.0 - -* restore_rate_beta: Beta parameter of beta distribution for rate that contamination decreases by after prevention effort. - - * Default: 3/7 - -* initial_rate_alpha: Alpha parameter of beta distribution for initial contamination fraction. - - * Default: 1.0 - -* initial_rate_beta: Beta parameter of beta distribution for initial contamination fraction. - - * Default: 30.0 - -* stages: Stage of food supply chain. - - * Default: 5 - -* prev_decision: Prevention decision. - - * Default: (0, 0, 0, 0, 0) - -Responses: ----------- -* level: A list of contamination levels over time. - - -References: -=========== -This model is adapted from the article "Contamination control in food supply chain" [1]. -Prepared by Kaeyoung Shin and Raghu Pasupathy of Virginia Tech, 12/18/2010. - -[1] Y. Hu, J. Hu, Y. Xu, and F. Wang. Contamination control in food supply -chain. In *Proceedings of the 2010 Winter Simulation Conference*, 2010. -https://dl.acm.org/doi/abs/10.5555/2433508.2433840 - - - -Optimization Problem: Minimize Prevention Costs (CONTAM-1) -========================================================== - -Decision Variables: -------------------- -* prev_decision - -Objectives: ------------ -Minimize the (deterministic) total cost of prevention efforts (prev_cost * prev_decision). - -.. image:: contam.PNG - :alt: The CONTAM formulation has failed to display - :width: 400 - -Constraints: ------------- -Each element of `prev_decision` is binary. (See above.) - -The contaminated fraction :math:`X_i` at the stage :math:`i` -should not exceed a pre-specified upper limit :math:`p_i` with -probability at least :math:`1 - \epsilon_i`. - -Problem Factors: ----------------- -* budget: Max # of replications for a solver to take. - - * Default: 10000 - -* prev_cost: Cost of prevention in each stage. - - * Default: [1, 1, 1, 1, 1] - -* error_prob: Allowable error probability in each stage. - - * Default: [0.2, 0.2, 0.2, 0.2, 0.2] - -* upper_thres: Upper limit of amount of contamination in each stage. - - * Default: [0.1, 0.1, 0.1, 0.1, 0.1] - -Fixed Model Factors: --------------------- -* N/A - -Starting Solution: ------------------- -* initial_solution: (1, 1, 1, 1, 1) - -Random Solutions: ------------------ -Generate a tuple of Bernoulli(0.5) random variables. - -Optimal Solution: ------------------ -Unknown - -Optimal Objective Function Value: ---------------------------------- -Unknown - - -Optimization Problem: ContaminationTotalCostCont (CONTAM-2) -=========================================================== - -Decision Variables: -------------------- -* prev_decision - -Objectives: ------------ -Minimize the (deterministic) total cost of prevention efforts (prev_cost * prev_decision). - -Constraints: ------------- -Each element of `prev_decision` in the interval [0, 1]. - -The contaminated fraction :math:`X_i` at the stage :math:`i` -should not exceed a pre-specified upper limit :math:`p_i` with -probability at least :math:`1 - \epsilon_i`. - -Problem Factors: ----------------- -* budget: Max # of replications for a solver to take. - - * Default: 10000 - -* prev_cost: Cost of prevention in each stage. - - * Default: [1, 1, 1, 1, 1] - -* error_prob: Allowable error probability in each stage. - - * Default: [0.2, 0.2, 0.2, 0.2, 0.2] - -* upper_thres: Upper limit of amount of contamination in each stage. - - * Default: [0.1, 0.1, 0.1, 0.1, 0.1] - -Fixed Model Factors: --------------------- -* N/A - -Starting Solution: ------------------- -* initial_solution: (1, 1, 1, 1, 1) - -Random Solutions: ------------------ -Generate a tuple of Uniform(0, 1) random variables. - -Optimal Solution: ------------------ -Unknown - -Optimal Objective Function Value: ---------------------------------- +Model: Contamination Control Problem (CONTAM) +============================================= + +Description: +------------ +Consider a food supply chain consisting of :math:`n` stages. Pathogenic microorganisms +and other poisonous elements can contaminate some fraction of the food supply at each +stage. Specifically, let the growth rate of contamination at stage :math:`i` of the +chain be denoted by the random variable :math:`\Lambda_i`, :math:`0 \leq \Lambda_i \leq 1` +for :math:`i = 1, 2, ..., n`. If a prevention effort is made at stage :math:`i`, +the contamination decreases by the random rate :math:`\Gamma_i`, :math:`0 \leq \Gamma_i \leq 1` +with associated prevention cost :math:`c_i`. Let the binary variable :math:`u_i` represent +whether a prevention measure is executed at stage :math:`i`. + + +Sources of Randomness: +---------------------- +1. Contamination rate :math:`\Lambda_i ~ Beta(1, \frac{17}{3})` for :math:`i = 1, 2, ..., n`; +2. Restoration rate :math:`\Gamma_i ~ Beta(1, \frac{3}{7})` for :math:`i = 1, 2, ..., n`; + +Model Factors: +-------------- +* contam_rate_alpha: Alpha parameter of beta distribution for growth rate of contamination at each stage. + + * Default: 1.0 + +* contam_rate_beta: Beta parameter of beta distribution for growth rate of contamination at each stage. + + * Default: 17/3 + +* restore_rate_alpha: Alpha parameter of beta distribution for rate that contamination decreases by after prevention effort. + + * Default: 1.0 + +* restore_rate_beta: Beta parameter of beta distribution for rate that contamination decreases by after prevention effort. + + * Default: 3/7 + +* initial_rate_alpha: Alpha parameter of beta distribution for initial contamination fraction. + + * Default: 1.0 + +* initial_rate_beta: Beta parameter of beta distribution for initial contamination fraction. + + * Default: 30.0 + +* stages: Stage of food supply chain. + + * Default: 5 + +* prev_decision: Prevention decision. + + * Default: (0, 0, 0, 0, 0) + +Responses: +---------- +* level: A list of contamination levels over time. + + +References: +=========== +This model is adapted from the article "Contamination control in food supply chain" [1]. +Prepared by Kaeyoung Shin and Raghu Pasupathy of Virginia Tech, 12/18/2010. + +[1] Y. Hu, J. Hu, Y. Xu, and F. Wang. Contamination control in food supply +chain. In *Proceedings of the 2010 Winter Simulation Conference*, 2010. +https://dl.acm.org/doi/abs/10.5555/2433508.2433840 + + + +Optimization Problem: Minimize Prevention Costs (CONTAM-1) +========================================================== + +Decision Variables: +------------------- +* prev_decision + +Objectives: +----------- +Minimize the (deterministic) total cost of prevention efforts (prev_cost * prev_decision). + +.. image:: contam.PNG + :alt: The CONTAM formulation has failed to display + :width: 400 + +Constraints: +------------ +Each element of `prev_decision` is binary. (See above.) + +The contaminated fraction :math:`X_i` at the stage :math:`i` +should not exceed a pre-specified upper limit :math:`p_i` with +probability at least :math:`1 - \epsilon_i`. + +Problem Factors: +---------------- +* budget: Max # of replications for a solver to take. + + * Default: 10000 + +* prev_cost: Cost of prevention in each stage. + + * Default: [1, 1, 1, 1, 1] + +* error_prob: Allowable error probability in each stage. + + * Default: [0.2, 0.2, 0.2, 0.2, 0.2] + +* upper_thres: Upper limit of amount of contamination in each stage. + + * Default: [0.1, 0.1, 0.1, 0.1, 0.1] + +Fixed Model Factors: +-------------------- +* N/A + +Starting Solution: +------------------ +* initial_solution: (1, 1, 1, 1, 1) + +Random Solutions: +----------------- +Generate a tuple of Bernoulli(0.5) random variables. + +Optimal Solution: +----------------- +Unknown + +Optimal Objective Function Value: +--------------------------------- +Unknown + + +Optimization Problem: ContaminationTotalCostCont (CONTAM-2) +=========================================================== + +Decision Variables: +------------------- +* prev_decision + +Objectives: +----------- +Minimize the (deterministic) total cost of prevention efforts (prev_cost * prev_decision). + +Constraints: +------------ +Each element of `prev_decision` in the interval [0, 1]. + +The contaminated fraction :math:`X_i` at the stage :math:`i` +should not exceed a pre-specified upper limit :math:`p_i` with +probability at least :math:`1 - \epsilon_i`. + +Problem Factors: +---------------- +* budget: Max # of replications for a solver to take. + + * Default: 10000 + +* prev_cost: Cost of prevention in each stage. + + * Default: [1, 1, 1, 1, 1] + +* error_prob: Allowable error probability in each stage. + + * Default: [0.2, 0.2, 0.2, 0.2, 0.2] + +* upper_thres: Upper limit of amount of contamination in each stage. + + * Default: [0.1, 0.1, 0.1, 0.1, 0.1] + +Fixed Model Factors: +-------------------- +* N/A + +Starting Solution: +------------------ +* initial_solution: (1, 1, 1, 1, 1) + +Random Solutions: +----------------- +Generate a tuple of Uniform(0, 1) random variables. + +Optimal Solution: +----------------- +Unknown + +Optimal Objective Function Value: +--------------------------------- Unknown \ No newline at end of file diff --git a/docs/data_farming_base.rst b/docs/source/data_farming_base.rst similarity index 95% rename from docs/data_farming_base.rst rename to docs/source/data_farming_base.rst index 213f88976..ba1f43956 100644 --- a/docs/data_farming_base.rst +++ b/docs/source/data_farming_base.rst @@ -1,7 +1,7 @@ -data\_farming\_base module -========================== - -.. automodule:: data_farming_base - :members: - :undoc-members: - :show-inheritance: +data\_farming\_base module +========================== + +.. automodule:: data_farming_base + :members: + :undoc-members: + :show-inheritance: diff --git a/docs/directory.rst b/docs/source/directory.rst similarity index 94% rename from docs/directory.rst rename to docs/source/directory.rst index 66d2384a8..67ef667db 100644 --- a/docs/directory.rst +++ b/docs/source/directory.rst @@ -1,7 +1,7 @@ -directory module -================ - -.. automodule:: directory - :members: - :undoc-members: - :show-inheritance: +directory module +================ + +.. automodule:: directory + :members: + :undoc-members: + :show-inheritance: diff --git a/docs/dualsourcing.rst b/docs/source/dualsourcing.rst similarity index 96% rename from docs/dualsourcing.rst rename to docs/source/dualsourcing.rst index 14f3dbfc6..0f18f6786 100644 --- a/docs/dualsourcing.rst +++ b/docs/source/dualsourcing.rst @@ -1,139 +1,139 @@ -Model: Dual Sourcing System (DUALSOURCING) -========================================== - -Description: ------------- -Consider a single-stage, incapacitated, manufacturing location facing stochastic demand. -The manufacturer can buy the material from a “regular” supplier at cost :math:`c_r` per unit, or, -if needed, she can get some or all of the material “expedited” at some premium cost :math:`c_e` -per unit with :math:`c_e > c_r`. -Regular orders arrive after :math:`l_r` periods while expedited orders arrive after :math:`l_e` periods with -:math:`l_e < l_r`. Let the difference in lead times be :math:`l = l_r − l_e ≥ 1`. - -If there is remaining on-hand inventory at the end of period :math:`n` (after demand :math:`d_n` is satisfied), -these items are carried over to the next period (i.e., :math:`I_n+1 > 0`) at a holding cost per unit. -However, if there is a stock-out (i.e., :math:`In + 1 < 0`), there is a penalty cost per unit -of unsatisfied demand. - -We will let the period :math:`n` expediting order be based on the on-hand inventory plus the orders that -will arrive within :math:`l_e` periods (both regular and expedited). Regular orders that are due to arrive -after :math:`l_e` periods are not considered in expedited ordering decisions. -The expedited order is placed to restore the expedited inventory position :math:`IP_n^e`, -to some target parameter level :math:`z_e`. The regular order :math:`X_n^r`, on the other hand, -is based on the regular inventory position (sum of on-hand inventory and all outstanding orders, -including the expedited order placed in the current period). Similarly, it tries to restore the regular -inventory position :math:`IP_n^r` to the target parameter :math:`z_r`. Thus, under this model, we carry two inventory positions, -one for regular orders and another for expedited orders. - -Sources of Randomness: ----------------------- -Demand follows a normal distribution. - -Model Factors: --------------- -* n_days: Number of days to simulate. - - * Default: 1000 - -* initial_inv: Initial inventory. - - * Default: 40 - -* cost_reg: Regular ordering cost per unit. - - * Default: 100.00 - -* cost_exp: Expedited ordering cost per unit. - - * Default: 110.00 - -* lead_reg: Lead time for regular orders in days. - - * Default: 110.00 - -* lead_exp: Lead time for expedited orders in days. - - * Default: 0 - -* holding_cost: Holding cost per unit per period. - - * Default: 5.00 - -* penalty_cost: Penalty cost per unit per period for backlogging. - - * Default: 495.00 - -* st_dev: Standard deviation of demand distribution. - - * Default: 10.0 - -* mu: Mean of demand distribution. - - * Default: 30.0 - -* order_level_reg: Order-up-to level for regular orders. - - * Default: 80 - -* order_level_exp: Order-up-to level for expedited orders. - - * Default: 50 - -Responses: ----------- -* average_holding_cost: The average holding cost over the time period. - -* average_penalty_cost: The average penalty cost over the time period. - -* average_ordering_cost: The average ordering cost over the time period. - -References: -=========== -This model is adapted from the article `Veeraraghavan, S and Scheller-Wolf, A. Now or Later: -A simple policy for Effective Dual Sourcing in Capacitated Systems. Operations Research (4), 850- 864. -`_ - - -Optimization Problem: Minimize total cost (DUALSOURCING-1) -========================================================== - -Decision Variables: -------------------- -* order_level_exp -* order_level_reg - -Objectives: ------------ -Minimize the expected total cost: sum of average_holding_cost, average_penalty_cost, average_ordering_cost. - -Constraints: ------------- -order_level_exp and order_level_reg are both non-negative. - -Problem Factors: ----------------- -* budget: Max # of replications for a solver to take. - - * Default: 1000 - -Fixed Model Factors: --------------------- -N/A - -Starting Solution: ------------------- -* order_level_exp: 50 - -* order_level_reg: 80 - -Random Solutions: ------------------ -Draw order_level_exp from Uniform(40,60) and order_level_reg from Uniform(70,90). - -Optimal Solution: ------------------ -Unknown. - -Optimal Objective Function Value: ---------------------------------- +Model: Dual Sourcing System (DUALSOURCING) +========================================== + +Description: +------------ +Consider a single-stage, incapacitated, manufacturing location facing stochastic demand. +The manufacturer can buy the material from a “regular” supplier at cost :math:`c_r` per unit, or, +if needed, she can get some or all of the material “expedited” at some premium cost :math:`c_e` +per unit with :math:`c_e > c_r`. +Regular orders arrive after :math:`l_r` periods while expedited orders arrive after :math:`l_e` periods with +:math:`l_e < l_r`. Let the difference in lead times be :math:`l = l_r − l_e ≥ 1`. + +If there is remaining on-hand inventory at the end of period :math:`n` (after demand :math:`d_n` is satisfied), +these items are carried over to the next period (i.e., :math:`I_n+1 > 0`) at a holding cost per unit. +However, if there is a stock-out (i.e., :math:`In + 1 < 0`), there is a penalty cost per unit +of unsatisfied demand. + +We will let the period :math:`n` expediting order be based on the on-hand inventory plus the orders that +will arrive within :math:`l_e` periods (both regular and expedited). Regular orders that are due to arrive +after :math:`l_e` periods are not considered in expedited ordering decisions. +The expedited order is placed to restore the expedited inventory position :math:`IP_n^e`, +to some target parameter level :math:`z_e`. The regular order :math:`X_n^r`, on the other hand, +is based on the regular inventory position (sum of on-hand inventory and all outstanding orders, +including the expedited order placed in the current period). Similarly, it tries to restore the regular +inventory position :math:`IP_n^r` to the target parameter :math:`z_r`. Thus, under this model, we carry two inventory positions, +one for regular orders and another for expedited orders. + +Sources of Randomness: +---------------------- +Demand follows a normal distribution. + +Model Factors: +-------------- +* n_days: Number of days to simulate. + + * Default: 1000 + +* initial_inv: Initial inventory. + + * Default: 40 + +* cost_reg: Regular ordering cost per unit. + + * Default: 100.00 + +* cost_exp: Expedited ordering cost per unit. + + * Default: 110.00 + +* lead_reg: Lead time for regular orders in days. + + * Default: 110.00 + +* lead_exp: Lead time for expedited orders in days. + + * Default: 0 + +* holding_cost: Holding cost per unit per period. + + * Default: 5.00 + +* penalty_cost: Penalty cost per unit per period for backlogging. + + * Default: 495.00 + +* st_dev: Standard deviation of demand distribution. + + * Default: 10.0 + +* mu: Mean of demand distribution. + + * Default: 30.0 + +* order_level_reg: Order-up-to level for regular orders. + + * Default: 80 + +* order_level_exp: Order-up-to level for expedited orders. + + * Default: 50 + +Responses: +---------- +* average_holding_cost: The average holding cost over the time period. + +* average_penalty_cost: The average penalty cost over the time period. + +* average_ordering_cost: The average ordering cost over the time period. + +References: +=========== +This model is adapted from the article `Veeraraghavan, S and Scheller-Wolf, A. Now or Later: +A simple policy for Effective Dual Sourcing in Capacitated Systems. Operations Research (4), 850- 864. +`_ + + +Optimization Problem: Minimize total cost (DUALSOURCING-1) +========================================================== + +Decision Variables: +------------------- +* order_level_exp +* order_level_reg + +Objectives: +----------- +Minimize the expected total cost: sum of average_holding_cost, average_penalty_cost, average_ordering_cost. + +Constraints: +------------ +order_level_exp and order_level_reg are both non-negative. + +Problem Factors: +---------------- +* budget: Max # of replications for a solver to take. + + * Default: 1000 + +Fixed Model Factors: +-------------------- +N/A + +Starting Solution: +------------------ +* order_level_exp: 50 + +* order_level_reg: 80 + +Random Solutions: +----------------- +Draw order_level_exp from Uniform(40,60) and order_level_reg from Uniform(70,90). + +Optimal Solution: +----------------- +Unknown. + +Optimal Objective Function Value: +--------------------------------- Unknown. \ No newline at end of file diff --git a/docs/dynamnews.rst b/docs/source/dynamnews.rst similarity index 96% rename from docs/dynamnews.rst rename to docs/source/dynamnews.rst index 8e5d62bac..95f77e747 100644 --- a/docs/dynamnews.rst +++ b/docs/source/dynamnews.rst @@ -1,125 +1,125 @@ -Model: Newsvendor under Dynamic Consumer Substitution (DYNAMNEWS) -================================================================= - -Description: ------------- -A retailer sells :math:`n` substitutable products :math:`j = 1, \ldots, n`, each with price :math:`p^j` and cost :math:`c^j`. -The initial inventory levels are denoted by :math:`x = (x_1, \ldots, x_n)`. - -Unlike in the classical newsvendor problem, the demand is not given by a predetermined distribution, -but depends on the initial inventory levels :math:`x` as well. The customers :math:`t = 1, \ldots, T` -arrive in order and each can choose one product that is in-stock when he/she arrives, namely any element in -:math:`S(x_t) = \{j : x^j_t > 0\} \cup \{0\}` where :math:`0` denotes the no-purchase option. - -Each customer :math:`t` assigns a utility :math:`U^j_t` to option :math:`j = 0, \ldots, n`, and thus :math:`U_t = (U^0_t, U^1_t, \ldots, U^n_t)` is his/her -vector of utilities. Note that :math:`U^j_t` is the utility of product :math:`j` net of the price :math:`p^j`, and therefore could be -negative. Since the *no-purchase* option :math:`0` incurs neither utility nor cost, one can assume :math:`U^0_t = 0`. -Customer :math:`t` makes their choice to maximize his/her utility - -.. math:: - d(x_t,U_t) = \argmax_{j\in S(x_t)} U^j_t - -Sources of Randomness: ----------------------- -1. Use the Multinomial Logit (MNL) model. :math:`U^0_t, U^1_t, \ldots, U^n_t` are mutually independent random variables -of the form - -.. math:: - U^j_t = u^j + \epsilon^j_t - -where :math:`u^j` is a constant and :math:`\epsilon^j_t`, :math:`j = 0, 1, \ldots, n` are mutually independent Gumbel random variables with -:math:`P(\epsilon^j_t \leq z) = \exp(-e^{-(z/\mu+\gamma)})` (:math:`\gamma` is Euler's constant, :math:`\gamma \approx 0.5772`.) - - -Model Factors: --------------- -* num_prod: Number of Products - - * Default: 2 - -* num_customer: Number of Customers - - * Default: 5 - -* c_utility: Constant of each product's utility - - * Default: (1.0, 1.0) - -* mu: Mu for calculating Gumbel random variable - - * Default: 1.0 - -* init_level: Initial inventory level - - * Default: (2, 3) - -* price: Sell price of products - - * Default: (9, 9) - -* cost: Cost of prodcuts - - * Default: (5, 5) - -An alternative setting has 10 products, 30 customers, linearly increasing utilities -(:math:`u^j = 5 + j`) and initial inventory levels :math:`(3, 3, \ldots, 3)`. - -Respones: ---------- -* profit: profit in this scenario - -* n_prod_stockout: number of products which are out of stock - - -References: -=========== -This model is adapted from the article Mahajan, S., & van Ryzin, G. (2001). -Stocking Retail Assortments under Dynamic Consumer Substitution. -*Operations Research*, 49(3), 334-351. -(https://pubsonline.informs.org/doi/abs/10.1287/opre.49.3.334.11210) - - -Optimization Problem: Maximize Profit ( 0\} \cup \{0\}` where :math:`0` denotes the no-purchase option. + +Each customer :math:`t` assigns a utility :math:`U^j_t` to option :math:`j = 0, \ldots, n`, and thus :math:`U_t = (U^0_t, U^1_t, \ldots, U^n_t)` is his/her +vector of utilities. Note that :math:`U^j_t` is the utility of product :math:`j` net of the price :math:`p^j`, and therefore could be +negative. Since the *no-purchase* option :math:`0` incurs neither utility nor cost, one can assume :math:`U^0_t = 0`. +Customer :math:`t` makes their choice to maximize his/her utility + +.. math:: + d(x_t,U_t) = \argmax_{j\in S(x_t)} U^j_t + +Sources of Randomness: +---------------------- +1. Use the Multinomial Logit (MNL) model. :math:`U^0_t, U^1_t, \ldots, U^n_t` are mutually independent random variables +of the form + +.. math:: + U^j_t = u^j + \epsilon^j_t + +where :math:`u^j` is a constant and :math:`\epsilon^j_t`, :math:`j = 0, 1, \ldots, n` are mutually independent Gumbel random variables with +:math:`P(\epsilon^j_t \leq z) = \exp(-e^{-(z/\mu+\gamma)})` (:math:`\gamma` is Euler's constant, :math:`\gamma \approx 0.5772`.) + + +Model Factors: +-------------- +* num_prod: Number of Products + + * Default: 2 + +* num_customer: Number of Customers + + * Default: 5 + +* c_utility: Constant of each product's utility + + * Default: (1.0, 1.0) + +* mu: Mu for calculating Gumbel random variable + + * Default: 1.0 + +* init_level: Initial inventory level + + * Default: (2, 3) + +* price: Sell price of products + + * Default: (9, 9) + +* cost: Cost of prodcuts + + * Default: (5, 5) + +An alternative setting has 10 products, 30 customers, linearly increasing utilities +(:math:`u^j = 5 + j`) and initial inventory levels :math:`(3, 3, \ldots, 3)`. + +Respones: +--------- +* profit: profit in this scenario + +* n_prod_stockout: number of products which are out of stock + + +References: +=========== +This model is adapted from the article Mahajan, S., & van Ryzin, G. (2001). +Stocking Retail Assortments under Dynamic Consumer Substitution. +*Operations Research*, 49(3), 334-351. +(https://pubsonline.informs.org/doi/abs/10.1287/opre.49.3.334.11210) + + +Optimization Problem: Maximize Profit ( 0` and rejected otherwise. When a request for product :math:`i` is -accepted, all of the booking limits that require the resources used by product :math:`i` -must be updated to account for the decrease in available resources. For example, -if a request for a 3-night stay arriving Monday is accepted, all products using a night -on either Monday, Tuesday, or Wednesday must have their booking limits decreased by one. - -We may see that :math:`b_i \leq C` (to avoid overbooking) and -that the highest booking limit must equal capacity (we want to rent as many rooms as -possible without going over capacity, thus, all rooms must be available to at least one -product). Furthermore, since requests are only accepted when rooms are available -(:math:`b_i > 0`), we are guaranteed to never go over capacity. - -In summary, a booking limit represents the maximum number of requests of product :math:`i` -that we are willing to accept given that we start with full availability. As soon as -a request is accepted, available capacity changes and booking limits must be updated -to account for this change. Although our interest is in modeling the full 56 products -to find the optimal set of booking limits, to illustrate how booking limits are updated, -one may look at the following, small-scale example: - -Assume a hotel offers only the following 5 products: -1. Two night stay arriving Monday. -2. Two night stay arriving Tuesday. -3. Two night stay arriving Wednesday. -4. Three night stay arriving Wednesday. -5. Two night stay arriving Thursday. - -If the booking limits for each product are :math:`b_1 = 10`, :math:`b_2 = 8`, :math:`b_3 = 4`, :math:`b_4 = 7`, -:math:`b_5 = 1` and the following requests are received, the booking limits would be updated -in the following way as decisions to accept or reject a given order are made: - -.. image:: hotel.PNG - :alt: The HOTEL table has failed to display - :width: 800 - -Note that, in this case, product 1 has a final booking limit of 9 as only one room -has been sold on either Monday or Tuesday, which means that 9 rooms are still available -on Monday night. - -To simplify this, one may create a binary matrix `A` showing which products use which -resources. Thus, we will let each row be a resource available and each column a product, -having a 1 in entry :math:`(i,j)` if product :math:`j` uses resource :math:`i`, and 0 -otherwise. Then, if we accept a request for product :math:`i`, we must update the booking -limits of all products :math:`j` such that :math:`A_j^T \cdot A_i \geq 1` (they share -at least one of the resources). For this small example, we have: - -.. image:: hotel2.PNG - :alt: The HOTEL matrix has failed to display - :width: 300 - -Sources of Randomness: ----------------------- -1. Stationary Poisson process with rate :math:`\lambda_i` for guest arrivals for product :math:`i`. - -Model Factors: --------------- -* num_products: Number of products: (rate, length of stay). - - * Default: 56 - -* lambda: Arrival rates for each product. - - * Default: Take :math:`\lambda_i = \frac{1}{168}, \frac{2}{168}, \frac{3}{168}, \frac{2}{168}, \frac{1}{168}, \frac{0.5}{168}, \frac{0.25}{168}` for 1-night, 2-night, ..., 7-night stay respectively. - -* num_rooms: Hotel capacity. - - * Default: 100 - -* discount_rate: Discount rate. - - * Default: 100 - -* rack_rate: Rack rate (full price). - - * Default: 200 - -* product_incidence: Incidence matrix. - - * Default: Let each row be a resource available and each column a product, having a 1 in entry :math:`(i,j)` if product :math:`j` uses resource :math:`i`, and 0 otherwise. - -* time_limit: Time after which orders of each product no longer arrive (e.g. Mon night stops at 3am Tues or t=27). - - * Default: list of 14 27's, 12 51's, 10 75's, 8 99's, 6 123's, 4 144's, and 2 168's - -* time_before: Hours before :math:`t=0` to start running (e.g. 168 means start at time -168). - - * Default: 168 - -* runlength: Runlength of simulation (in hours) after t=0. - - * Default: 168 - -* booking_limits: Booking limits. - - * Default: tuple of 56 100's - -Responses: ----------- -* revenue: Expected revenue. - - -References: -=========== -N/A - - - - -Optimization Problem: Maximize Revenue (HOTEL-1) -================================================ - -Decision Variables: -------------------- -* booking_limits - -Objectives: ------------ -Maximize the expected revenue. - -Constraints: ------------- -Lower bounded by 0 and upper bounded by the total number of rooms. - -Problem Factors: ----------------- -* budget: Max # of replications for a solver to take. - - * Default: 10000 - -Fixed Model Factors: --------------------- -* N/A - -Starting Solution: ------------------- -* initial_solution: Initial solution. - - * Default: tuple of 56 zeros - -Random Solutions: ------------------ -Let each :math:`b_i` (element in tuple) be distributed Uniformly :math:`(0, C)`. - -Optimal Solution: ------------------ -Unknown - -Optimal Objective Function Value: ---------------------------------- +Model: Hotel Revenue Management (HOTEL) +======================================= + +Description: +------------ +Most of the revenue for a hotel comes from guests staying in its rooms. Assume a +given hotel has only two rates: rack rate and discount rate, which pay :math:`p_f` +and :math:`p_d` per night, respectively. Furthermore, let each different combination +of length of stay, arrival date and rate paid be a "product" so that the following +56 products are available to satisfy one week's worth of capacity (14 arriving Monday, +12 arriving Tuesday, ..., 2 Arriving Sunday): + +1. One night stay, rack rate arriving Monday +2. One night stay, discount rate arriving Monday +3. Two night stay, rack rate arriving Monday +4. Two night stay, discount rate arriving Monday +5. ... +55. One night stay, rack rate arriving Sunday +56. One night stay, discount rate arriving Sunday + +For a given stay, the hotel collects revenue equal to the (rate paid) x (length of stay). +Lastly, let the arrival processes for each product be a stationary Poisson process with +rate :math:`\lambda_i`, noting that orders for a Monday night stay stop arriving at +3 AM Tuesday night, for a Tuesday night stay at 3 AM Wednesday, and so on. + +Booking limits (:math:`b_1, ..., b_{56}`) are controls +that limit the amount of capacity that can be sold to any particular product; i.e., +they represent the maximum number of requests of product :math:`i` we are willing to +accept. The booking limits do not represent the number of rooms +reserved for each product, rather, they represent the number of rooms available to +this product and all products that use the same resources and have a higher booking limit. +For example, if we have five products and all of them require the same resource (say capacity +:math:`C = 10`) and their corresponding booking limits are :math:`b_1 = 10`, :math:`b_2 = 8`, +:math:`b_3 = 4`, :math:`b_4 = 2`, :math:`b_5 = 1`, we know we can only take 1 request for product 5, 2 requests +for product 4 and so on. However, this **does not mean that 2 rooms will be saved** +until 2 requests for product 4 arrive; **rather**, it means that, **out of all requests +accepted, at most 2 can be of product 4**. Note also that the maximum number of requests +accepted in this case would be 10, as they all use the same resource, which has :math:`C = 10`. +Doing this ensures that those products with higher booking limits are always accepted +if capacity is available while also accounting for the interconnectedness of the system. + +Now, once the booking limits are set, a request for product :math:`i` is accepted if +and only if :math:`b_i > 0` and rejected otherwise. When a request for product :math:`i` is +accepted, all of the booking limits that require the resources used by product :math:`i` +must be updated to account for the decrease in available resources. For example, +if a request for a 3-night stay arriving Monday is accepted, all products using a night +on either Monday, Tuesday, or Wednesday must have their booking limits decreased by one. + +We may see that :math:`b_i \leq C` (to avoid overbooking) and +that the highest booking limit must equal capacity (we want to rent as many rooms as +possible without going over capacity, thus, all rooms must be available to at least one +product). Furthermore, since requests are only accepted when rooms are available +(:math:`b_i > 0`), we are guaranteed to never go over capacity. + +In summary, a booking limit represents the maximum number of requests of product :math:`i` +that we are willing to accept given that we start with full availability. As soon as +a request is accepted, available capacity changes and booking limits must be updated +to account for this change. Although our interest is in modeling the full 56 products +to find the optimal set of booking limits, to illustrate how booking limits are updated, +one may look at the following, small-scale example: + +Assume a hotel offers only the following 5 products: +1. Two night stay arriving Monday. +2. Two night stay arriving Tuesday. +3. Two night stay arriving Wednesday. +4. Three night stay arriving Wednesday. +5. Two night stay arriving Thursday. + +If the booking limits for each product are :math:`b_1 = 10`, :math:`b_2 = 8`, :math:`b_3 = 4`, :math:`b_4 = 7`, +:math:`b_5 = 1` and the following requests are received, the booking limits would be updated +in the following way as decisions to accept or reject a given order are made: + +.. image:: hotel.PNG + :alt: The HOTEL table has failed to display + :width: 800 + +Note that, in this case, product 1 has a final booking limit of 9 as only one room +has been sold on either Monday or Tuesday, which means that 9 rooms are still available +on Monday night. + +To simplify this, one may create a binary matrix `A` showing which products use which +resources. Thus, we will let each row be a resource available and each column a product, +having a 1 in entry :math:`(i,j)` if product :math:`j` uses resource :math:`i`, and 0 +otherwise. Then, if we accept a request for product :math:`i`, we must update the booking +limits of all products :math:`j` such that :math:`A_j^T \cdot A_i \geq 1` (they share +at least one of the resources). For this small example, we have: + +.. image:: hotel2.PNG + :alt: The HOTEL matrix has failed to display + :width: 300 + +Sources of Randomness: +---------------------- +1. Stationary Poisson process with rate :math:`\lambda_i` for guest arrivals for product :math:`i`. + +Model Factors: +-------------- +* num_products: Number of products: (rate, length of stay). + + * Default: 56 + +* lambda: Arrival rates for each product. + + * Default: Take :math:`\lambda_i = \frac{1}{168}, \frac{2}{168}, \frac{3}{168}, \frac{2}{168}, \frac{1}{168}, \frac{0.5}{168}, \frac{0.25}{168}` for 1-night, 2-night, ..., 7-night stay respectively. + +* num_rooms: Hotel capacity. + + * Default: 100 + +* discount_rate: Discount rate. + + * Default: 100 + +* rack_rate: Rack rate (full price). + + * Default: 200 + +* product_incidence: Incidence matrix. + + * Default: Let each row be a resource available and each column a product, having a 1 in entry :math:`(i,j)` if product :math:`j` uses resource :math:`i`, and 0 otherwise. + +* time_limit: Time after which orders of each product no longer arrive (e.g. Mon night stops at 3am Tues or t=27). + + * Default: list of 14 27's, 12 51's, 10 75's, 8 99's, 6 123's, 4 144's, and 2 168's + +* time_before: Hours before :math:`t=0` to start running (e.g. 168 means start at time -168). + + * Default: 168 + +* runlength: Runlength of simulation (in hours) after t=0. + + * Default: 168 + +* booking_limits: Booking limits. + + * Default: tuple of 56 100's + +Responses: +---------- +* revenue: Expected revenue. + + +References: +=========== +N/A + + + + +Optimization Problem: Maximize Revenue (HOTEL-1) +================================================ + +Decision Variables: +------------------- +* booking_limits + +Objectives: +----------- +Maximize the expected revenue. + +Constraints: +------------ +Lower bounded by 0 and upper bounded by the total number of rooms. + +Problem Factors: +---------------- +* budget: Max # of replications for a solver to take. + + * Default: 10000 + +Fixed Model Factors: +-------------------- +* N/A + +Starting Solution: +------------------ +* initial_solution: Initial solution. + + * Default: tuple of 56 zeros + +Random Solutions: +----------------- +Let each :math:`b_i` (element in tuple) be distributed Uniformly :math:`(0, C)`. + +Optimal Solution: +----------------- +Unknown + +Optimal Objective Function Value: +--------------------------------- Unknown \ No newline at end of file diff --git a/docs/index.rst b/docs/source/index.rst similarity index 98% rename from docs/index.rst rename to docs/source/index.rst index 47a4be7fb..cd9b4f908 100644 --- a/docs/index.rst +++ b/docs/source/index.rst @@ -1,46 +1,46 @@ -.. SimOpt documentation master file, created by - sphinx-quickstart on Tue May 4 15:52:46 2021. - You can adapt this file completely to your liking, but it should at least - contain the root `toctree` directive. - -Welcome to SimOpt's documentation! -================================== - -The purpose of the SimOpt testbed is to encourage development and constructive comparison of simulation-optimization (SO) solvers (algorithms). We are particularly interested in the finite-time performance of solvers, rather than the asymptotic results that one often finds in related literature. - -For the purposes of this site, we define simulation as a very general technique for estimating statistical measures of complex systems. A system is modeled as if the probability distributions of the underlying random variables were known. Realizations of these random variables are then drawn randomly from these distributions. Each replication gives one observation of the system response, i.e., an evaluation of the objective function. By simulating a system in this fashion for multiple replications and aggregating the responses, one can compute statistics and use them for evaluation and design. - -The paper `Pasupathy and Henderson (2006) `_ explains the original motivation for the testbed, and the follow-up paper `Pasupathy and Henderson (2011) `_ describes an earlier interface for MATLAB implementations of problems and solvers. The paper `Dong et al. (2017) `_ conducts an experimental comparison of several solvers in SimOpt and analyzes their relative performance. The recent Winter Simulation Conference paper `Eckman et al. (2019) `_ describes in detail the recent changes to the architecture of SimOpt and the control of random number streams. - -The `models `_ library contains the simulation logic to simulate a variety of systems and SO test problems built around these models. The `solvers `_ library provides users with the latest SO solvers to solve different types of SO problems. The two libraries are intended to help researchers evaluate and compare the finite-time performance of existing solvers. - -The source code consists of the following modules: - -* The `base.py `_ module contains class definitions for models, problems, and solvers. - -* The `experiment_base.py `_ module contains class definitions and functions for running experiments with simulation-optimization solvers. - -* The `data_farming_base.py `_ module contains class definitions and functions for running data-farming experiments. - -* The `directory.py `_ module contains a listing of models, problems, and solvers in the library. - -Getting Started ----------------- - -Please make sure you have the following dependencies installed: Python 3, numpy, scipy, matplotlib, seaborn, and mrg32k3a. Then clone the repo. To see an example of how to run an experiment on a solver and problem pair, please view or run demo/demo\_problem\_solver.py. - -Contents --------- - -.. toctree:: - :maxdepth: 4 - - modules - - -Acknowledgments -------------------- - -An earlier website for `SimOpt `_ was developed through work supported by the National Science Foundation under grant nos. DMI-0400287, CMMI-0800688 and CMMI-1200315. -Recent work on the development of SimOpt has been supported by the National Science Foundation under grant nos. DGE-1650441, CMMI-1537394, CMMI-1254298, CMMI-1536895, IIS-1247696, and TRIPODS+X DMS-1839346, by the Air Force Office of Scientific Research under grant nos. FA9550-12-1-0200, FA9550-15-1-0038, and FA9550-16-1-0046, and by the Army Research Office under grant no. W911NF-17-1-0094. -Any opinions, findings and conclusions or recommendations expressed in this material are those of the authors and do not necessarily reflect the views of the National Science Foundation (NSF). +.. SimOpt documentation master file, created by + sphinx-quickstart on Tue May 4 15:52:46 2021. + You can adapt this file completely to your liking, but it should at least + contain the root `toctree` directive. + +Welcome to SimOpt's documentation! +================================== + +The purpose of the SimOpt testbed is to encourage development and constructive comparison of simulation-optimization (SO) solvers (algorithms). We are particularly interested in the finite-time performance of solvers, rather than the asymptotic results that one often finds in related literature. + +For the purposes of this site, we define simulation as a very general technique for estimating statistical measures of complex systems. A system is modeled as if the probability distributions of the underlying random variables were known. Realizations of these random variables are then drawn randomly from these distributions. Each replication gives one observation of the system response, i.e., an evaluation of the objective function. By simulating a system in this fashion for multiple replications and aggregating the responses, one can compute statistics and use them for evaluation and design. + +The paper `Pasupathy and Henderson (2006) `_ explains the original motivation for the testbed, and the follow-up paper `Pasupathy and Henderson (2011) `_ describes an earlier interface for MATLAB implementations of problems and solvers. The paper `Dong et al. (2017) `_ conducts an experimental comparison of several solvers in SimOpt and analyzes their relative performance. The recent Winter Simulation Conference paper `Eckman et al. (2019) `_ describes in detail the recent changes to the architecture of SimOpt and the control of random number streams. + +The `models `_ library contains the simulation logic to simulate a variety of systems and SO test problems built around these models. The `solvers `_ library provides users with the latest SO solvers to solve different types of SO problems. The two libraries are intended to help researchers evaluate and compare the finite-time performance of existing solvers. + +The source code consists of the following modules: + +* The `base.py `_ module contains class definitions for models, problems, and solvers. + +* The `experiment_base.py `_ module contains class definitions and functions for running experiments with simulation-optimization solvers. + +* The `data_farming_base.py `_ module contains class definitions and functions for running data-farming experiments. + +* The `directory.py `_ module contains a listing of models, problems, and solvers in the library. + +Getting Started +---------------- + +Please make sure you have the following dependencies installed: Python 3, numpy, scipy, matplotlib, seaborn, and mrg32k3a. Then clone the repo. To see an example of how to run an experiment on a solver and problem pair, please view or run demo/demo\_problem\_solver.py. + +Contents +-------- + +.. toctree:: + :maxdepth: 4 + + modules + + +Acknowledgments +------------------- + +An earlier website for `SimOpt `_ was developed through work supported by the National Science Foundation under grant nos. DMI-0400287, CMMI-0800688 and CMMI-1200315. +Recent work on the development of SimOpt has been supported by the National Science Foundation under grant nos. DGE-1650441, CMMI-1537394, CMMI-1254298, CMMI-1536895, IIS-1247696, and TRIPODS+X DMS-1839346, by the Air Force Office of Scientific Research under grant nos. FA9550-12-1-0200, FA9550-15-1-0038, and FA9550-16-1-0046, and by the Army Research Office under grant no. W911NF-17-1-0094. +Any opinions, findings and conclusions or recommendations expressed in this material are those of the authors and do not necessarily reflect the views of the National Science Foundation (NSF). diff --git a/docs/ironore.rst b/docs/source/ironore.rst similarity index 96% rename from docs/ironore.rst rename to docs/source/ironore.rst index 32528e66a..9689049e2 100644 --- a/docs/ironore.rst +++ b/docs/source/ironore.rst @@ -1,154 +1,154 @@ -Model: Iron Ore Production with Exogenous Stochastic Price (IRONORE) -==================================================================== - -Description: ------------- -Iron ore is traded on the spot market, facing an exogenous, stochastic price. There -is enormous demand for iron, and so for the purposes of a small or medium-sized iron ore mine, we assume -that any quantity of ore can be instantaneously sold at current market rates. - -Let there be :math:`T` time periods (days), holding cost of :math:`h` per unit, production cost of :math:`c` per unit, -maximum production per day of :math:`m` units, and maximum holding capacity of :math:`K` units. Let the iron ore market price for -the day be :math:`P_t`. - -Let :math:`x_1` be the price at which to begin production, :math:`x_2` be the inventory level at which to cease production, -:math:`x_3` be the price at which to cease production, and :math:`x_4` be the price at which to sell all current stock. - -The daily order of operations in the simulation is as follows: - - 1. Sample the market price, :math:`P_t`. Let current stock be :math:`s_t`. - - 2. If production is already underway, - - (a) if :math:`P_t` ≤ :math:`x_3` or :math:`s_t` ≥ :math:`x_2`, cease production. - - (b) else, produce :math:`min(m, K − s_t)` at cost :math:`c` per unit. - - 3. If production is not currently underway, and if :math:`P_t` ≥ :math:`x_1` and :math:`s_t` < :math:`x_2`, begin production. - - 4. If :math:`P_t` ≥ :math:`x_4`, sell all stock (after production) at price :math:`P_t`. - - 5. Charge a holding cost of :math:`h` per unit (after production and sales). - -Sources of Randomness: ----------------------- -1. Let :math:`P_t` be a meanreverting random walk, such that :math:`P_t = \mbox{trunc}(P_t - 1 + N_t (\mu,\sigma))`, -where :math:`N_t` is a normal random variable with standard deviation :math:`\sigma` and mean :math:`\mu_t = \mbox{sgn}(\mu_0 − P_t−1) * (| \mu_0 − P_t − 1 |)^{\frac{1}{4}}`. -Here :math:`\mbox{trunc}(x)` truncates the price to lie between a specified minimum and maximum price. - -Model Factors: --------------- -* mean_price: Mean iron ore price per unit. - - * Default: 100.0 - -* max_price: Maximum iron ore price per unit. - - * Default: 200.0 - -* min_price: Minimum iron ore price per unit. - - * Default: 0.0 - -* capacity: Maximum holding capacity. - - * Default: 10000 - -* st_dev: Standard deviation of random walk steps for price. - - * Default: 7.5 - -* holding_cost: Holding cost per unit per period. - - * Default: 1.0 - -* prod_cost: Production cost per unit. - - * Default: 100.0 - -* max_prod_perday: Maximum units produced per day. - - * Default: 100 - -* price_prod: Price level to start production. - - * Default: 80.0 - -* inven_stop: Inventory level to cease production. - - * Default: 7000 - -* price_stop: Price level to stop production. - - * Default: 40 - -* price_sell: Price level to sell all stock. - - * Default: 100 - -* n_days: Number of days to simulate. - - * Default: 365 - - -Respones: ---------- -* total_profit: The total profit over the time period - -* frac_producing: The fraction of days spent producing iron ore - -* mean_stock: The average stocks over the time period - - -References: -=========== -N/A - - -Optimization Problem: Maximize Profit (IRONORE-1) -================================================= - -Decision Variables: -------------------- -* price_prod -* inven_stop -* price_stop -* price_sell - -Objectives: ------------ -Maximize total_profit over the :math:`T` time periods. - -Constraints: ------------- -All decision variables should be non-negative. -Logically, we should also have price_stop <= price_prod <= price_sell, but this is not enforced. - -Problem Factors: ----------------- -* budget: Max # of replications for a solver to take - - * Default: 1000 - -Fixed Model Factors: --------------------- -* N/A - -Starting Solution: ------------------- -* initial_solution: :math:`x_1 = 80`, :math:`x_2 = 7000`, :math:`x_3 = 40`, :math:`x_4=100` - -Random Solutions: ------------------ -* :math:`x_1`: Sample an lognormal random variate with 2.5- and 97.5-percentiles of 10 and 200. -* :math:`x_2`: Sample an lognormal random variate with 2.5- and 97.5-percentiles of 1000 and 10000. -* :math:`x_3`: Sample an lognormal random variate with 2.5- and 97.5-percentiles of 10 and 200. -* :math:`x_4`: Sample an lognormal random variate with 2.5- and 97.5-percentiles of 10 and 200. - -Optimal Solution: ------------------ -Unknown - -Optimal Objective Function Value: ---------------------------------- -Unknown +Model: Iron Ore Production with Exogenous Stochastic Price (IRONORE) +==================================================================== + +Description: +------------ +Iron ore is traded on the spot market, facing an exogenous, stochastic price. There +is enormous demand for iron, and so for the purposes of a small or medium-sized iron ore mine, we assume +that any quantity of ore can be instantaneously sold at current market rates. + +Let there be :math:`T` time periods (days), holding cost of :math:`h` per unit, production cost of :math:`c` per unit, +maximum production per day of :math:`m` units, and maximum holding capacity of :math:`K` units. Let the iron ore market price for +the day be :math:`P_t`. + +Let :math:`x_1` be the price at which to begin production, :math:`x_2` be the inventory level at which to cease production, +:math:`x_3` be the price at which to cease production, and :math:`x_4` be the price at which to sell all current stock. + +The daily order of operations in the simulation is as follows: + + 1. Sample the market price, :math:`P_t`. Let current stock be :math:`s_t`. + + 2. If production is already underway, + + (a) if :math:`P_t` ≤ :math:`x_3` or :math:`s_t` ≥ :math:`x_2`, cease production. + + (b) else, produce :math:`min(m, K − s_t)` at cost :math:`c` per unit. + + 3. If production is not currently underway, and if :math:`P_t` ≥ :math:`x_1` and :math:`s_t` < :math:`x_2`, begin production. + + 4. If :math:`P_t` ≥ :math:`x_4`, sell all stock (after production) at price :math:`P_t`. + + 5. Charge a holding cost of :math:`h` per unit (after production and sales). + +Sources of Randomness: +---------------------- +1. Let :math:`P_t` be a meanreverting random walk, such that :math:`P_t = \mbox{trunc}(P_t - 1 + N_t (\mu,\sigma))`, +where :math:`N_t` is a normal random variable with standard deviation :math:`\sigma` and mean :math:`\mu_t = \mbox{sgn}(\mu_0 − P_t−1) * (| \mu_0 − P_t − 1 |)^{\frac{1}{4}}`. +Here :math:`\mbox{trunc}(x)` truncates the price to lie between a specified minimum and maximum price. + +Model Factors: +-------------- +* mean_price: Mean iron ore price per unit. + + * Default: 100.0 + +* max_price: Maximum iron ore price per unit. + + * Default: 200.0 + +* min_price: Minimum iron ore price per unit. + + * Default: 0.0 + +* capacity: Maximum holding capacity. + + * Default: 10000 + +* st_dev: Standard deviation of random walk steps for price. + + * Default: 7.5 + +* holding_cost: Holding cost per unit per period. + + * Default: 1.0 + +* prod_cost: Production cost per unit. + + * Default: 100.0 + +* max_prod_perday: Maximum units produced per day. + + * Default: 100 + +* price_prod: Price level to start production. + + * Default: 80.0 + +* inven_stop: Inventory level to cease production. + + * Default: 7000 + +* price_stop: Price level to stop production. + + * Default: 40 + +* price_sell: Price level to sell all stock. + + * Default: 100 + +* n_days: Number of days to simulate. + + * Default: 365 + + +Respones: +--------- +* total_profit: The total profit over the time period + +* frac_producing: The fraction of days spent producing iron ore + +* mean_stock: The average stocks over the time period + + +References: +=========== +N/A + + +Optimization Problem: Maximize Profit (IRONORE-1) +================================================= + +Decision Variables: +------------------- +* price_prod +* inven_stop +* price_stop +* price_sell + +Objectives: +----------- +Maximize total_profit over the :math:`T` time periods. + +Constraints: +------------ +All decision variables should be non-negative. +Logically, we should also have price_stop <= price_prod <= price_sell, but this is not enforced. + +Problem Factors: +---------------- +* budget: Max # of replications for a solver to take + + * Default: 1000 + +Fixed Model Factors: +-------------------- +* N/A + +Starting Solution: +------------------ +* initial_solution: :math:`x_1 = 80`, :math:`x_2 = 7000`, :math:`x_3 = 40`, :math:`x_4=100` + +Random Solutions: +----------------- +* :math:`x_1`: Sample an lognormal random variate with 2.5- and 97.5-percentiles of 10 and 200. +* :math:`x_2`: Sample an lognormal random variate with 2.5- and 97.5-percentiles of 1000 and 10000. +* :math:`x_3`: Sample an lognormal random variate with 2.5- and 97.5-percentiles of 10 and 200. +* :math:`x_4`: Sample an lognormal random variate with 2.5- and 97.5-percentiles of 10 and 200. + +Optimal Solution: +----------------- +Unknown + +Optimal Objective Function Value: +--------------------------------- +Unknown diff --git a/docs/main.rst b/docs/source/main.rst similarity index 93% rename from docs/main.rst rename to docs/source/main.rst index eace87b83..5eb2c3ae4 100644 --- a/docs/main.rst +++ b/docs/source/main.rst @@ -1,7 +1,7 @@ -main module -=========== - -.. automodule:: main - :members: - :undoc-members: - :show-inheritance: +main module +=========== + +.. automodule:: main + :members: + :undoc-members: + :show-inheritance: diff --git a/docs/mm1queue.rst b/docs/source/mm1queue.rst similarity index 95% rename from docs/mm1queue.rst rename to docs/source/mm1queue.rst index a21147b51..2abb300e9 100644 --- a/docs/mm1queue.rst +++ b/docs/source/mm1queue.rst @@ -1,94 +1,94 @@ -Model: M/M/1 Queue -================== - -Description: ------------- -This is a model simulates an M/M/1 queue with an Exponential -interarrival time distribution and an Exponential service time -distribution. - -Sources of Randomness: ----------------------- -1. Exponential interarrival times. -2. Exponential service times. - -Model Factors: --------------- -* lambda: Rate parameter of interarrival time distribution. - - * Default: 1.5 - -* mu: Rate parameter of service time distribution. - - * Default 3.0 - -* warmup: Represents the number of people as warmup before collecting statistics - - * Default: 50 - -* people: Represents the number of people from which to calculate the average sojourn time. - - * Default: 200 - -Respones: ---------- -* avg_sojourn_time: The average of sojourn time of customers (time customers spend in the system). - -* avg_waiting_time: The average of waiting time of customers. - -* frac_cust_wait: The fraction of customers who wait. - - -References: -=========== -This example is adapted from Cheng, R and Kleijnen,J.(1999). Improved Design of Queueing Simulation Experience with Highly Heteroscedastic Responses. Operations Research, v. 47, n. 5, pp. 762-777 (https://pubsonline.informs.org/doi/abs/10.1287/opre.47.5.762) - - - -Optimization Problem: Minimize average sojourn time plus penalty (MM1-1) -======================================================================== - - -Decision Variables: -------------------- -* mu (service rate parameter) - - -Objectives: ------------ -Minimize the expected average sojourn time plus a penalty for increasing the rate :math:`c\mu^2`. - -Constraints: ------------- -No deterministic or stochastic constraints. -Box constraints for non-negativity of mu. - -Problem Factors: ----------------- -* budget: Max # of replications for a solver to take. - - * Default: 1000 - -* cost: Cost for increasing service rate. - - * Default: 0.1 - -Fixed Model Factors: --------------------- -None - -Starting Solution: ------------------- -* mu: 3.0 - -Random Solutions: ------------------ -Generate mu from an exponential distribution with mean 3. - -Optimal Solution: ------------------ -None. - -Optimal Objective Function Value: ---------------------------------- -None. +Model: M/M/1 Queue +================== + +Description: +------------ +This is a model simulates an M/M/1 queue with an Exponential +interarrival time distribution and an Exponential service time +distribution. + +Sources of Randomness: +---------------------- +1. Exponential interarrival times. +2. Exponential service times. + +Model Factors: +-------------- +* lambda: Rate parameter of interarrival time distribution. + + * Default: 1.5 + +* mu: Rate parameter of service time distribution. + + * Default 3.0 + +* warmup: Represents the number of people as warmup before collecting statistics + + * Default: 50 + +* people: Represents the number of people from which to calculate the average sojourn time. + + * Default: 200 + +Respones: +--------- +* avg_sojourn_time: The average of sojourn time of customers (time customers spend in the system). + +* avg_waiting_time: The average of waiting time of customers. + +* frac_cust_wait: The fraction of customers who wait. + + +References: +=========== +This example is adapted from Cheng, R and Kleijnen,J.(1999). Improved Design of Queueing Simulation Experience with Highly Heteroscedastic Responses. Operations Research, v. 47, n. 5, pp. 762-777 (https://pubsonline.informs.org/doi/abs/10.1287/opre.47.5.762) + + + +Optimization Problem: Minimize average sojourn time plus penalty (MM1-1) +======================================================================== + + +Decision Variables: +------------------- +* mu (service rate parameter) + + +Objectives: +----------- +Minimize the expected average sojourn time plus a penalty for increasing the rate :math:`c\mu^2`. + +Constraints: +------------ +No deterministic or stochastic constraints. +Box constraints for non-negativity of mu. + +Problem Factors: +---------------- +* budget: Max # of replications for a solver to take. + + * Default: 1000 + +* cost: Cost for increasing service rate. + + * Default: 0.1 + +Fixed Model Factors: +-------------------- +None + +Starting Solution: +------------------ +* mu: 3.0 + +Random Solutions: +----------------- +Generate mu from an exponential distribution with mean 3. + +Optimal Solution: +----------------- +None. + +Optimal Objective Function Value: +--------------------------------- +None. diff --git a/docs/models.rst b/docs/source/models.rst similarity index 94% rename from docs/models.rst rename to docs/source/models.rst index 2f13c6697..e975db803 100644 --- a/docs/models.rst +++ b/docs/source/models.rst @@ -1,133 +1,133 @@ -models package -============== - -Submodules ----------- - -models.chessmm module ---------------------- - -.. automodule:: models.chessmm - :members: - :undoc-members: - :show-inheritance: - -models.cntnv module -------------------- - -.. automodule:: models.cntnv - :members: - :undoc-members: - :show-inheritance: - -models.contam module --------------------- - -.. automodule:: models.contam - :members: - :undoc-members: - :show-inheritance: - -models.dualsourcing module --------------------------- - -.. automodule:: models.dualsourcing - :members: - :undoc-members: - :show-inheritance: - -models.dynamnews module ------------------------ - -.. automodule:: models.dynamnews - :members: - :undoc-members: - :show-inheritance: - -models.facilitysizing module ----------------------------- - -.. automodule:: models.facilitysizing - :members: - :undoc-members: - :show-inheritance: - -models.fixedsan module ----------------------- - -.. automodule:: models.fixedsan - :members: - :undoc-members: - :show-inheritance: - -models.hotel module -------------------- - -.. automodule:: models.hotel - :members: - :undoc-members: - :show-inheritance: - -models.ironore module ---------------------- - -.. automodule:: models.ironore - :members: - :undoc-members: - :show-inheritance: - -models.mm1queue module ----------------------- - -.. automodule:: models.mm1queue - :members: - :undoc-members: - :show-inheritance: - -models.paramesti module ------------------------ - -.. automodule:: models.paramesti - :members: - :undoc-members: - :show-inheritance: - -models.rmitd module -------------------- - -.. automodule:: models.rmitd - :members: - :undoc-members: - :show-inheritance: - -models.san module ------------------ - -.. automodule:: models.san - :members: - :undoc-members: - :show-inheritance: - -models.sscont module --------------------- - -.. automodule:: models.sscont - :members: - :undoc-members: - :show-inheritance: - -models.tableallocation module ------------------------------ - -.. automodule:: models.tableallocation - :members: - :undoc-members: - :show-inheritance: - -Module contents ---------------- - -.. automodule:: models - :members: - :undoc-members: - :show-inheritance: +models package +============== + +Submodules +---------- + +models.chessmm module +--------------------- + +.. automodule:: models.chessmm + :members: + :undoc-members: + :show-inheritance: + +models.cntnv module +------------------- + +.. automodule:: models.cntnv + :members: + :undoc-members: + :show-inheritance: + +models.contam module +-------------------- + +.. automodule:: models.contam + :members: + :undoc-members: + :show-inheritance: + +models.dualsourcing module +-------------------------- + +.. automodule:: models.dualsourcing + :members: + :undoc-members: + :show-inheritance: + +models.dynamnews module +----------------------- + +.. automodule:: models.dynamnews + :members: + :undoc-members: + :show-inheritance: + +models.facilitysizing module +---------------------------- + +.. automodule:: models.facilitysizing + :members: + :undoc-members: + :show-inheritance: + +models.fixedsan module +---------------------- + +.. automodule:: models.fixedsan + :members: + :undoc-members: + :show-inheritance: + +models.hotel module +------------------- + +.. automodule:: models.hotel + :members: + :undoc-members: + :show-inheritance: + +models.ironore module +--------------------- + +.. automodule:: models.ironore + :members: + :undoc-members: + :show-inheritance: + +models.mm1queue module +---------------------- + +.. automodule:: models.mm1queue + :members: + :undoc-members: + :show-inheritance: + +models.paramesti module +----------------------- + +.. automodule:: models.paramesti + :members: + :undoc-members: + :show-inheritance: + +models.rmitd module +------------------- + +.. automodule:: models.rmitd + :members: + :undoc-members: + :show-inheritance: + +models.san module +----------------- + +.. automodule:: models.san + :members: + :undoc-members: + :show-inheritance: + +models.sscont module +-------------------- + +.. automodule:: models.sscont + :members: + :undoc-members: + :show-inheritance: + +models.tableallocation module +----------------------------- + +.. automodule:: models.tableallocation + :members: + :undoc-members: + :show-inheritance: + +Module contents +--------------- + +.. automodule:: models + :members: + :undoc-members: + :show-inheritance: diff --git a/docs/modules.rst b/docs/source/modules.rst similarity index 88% rename from docs/modules.rst rename to docs/source/modules.rst index f483d72ec..5681d6dce 100644 --- a/docs/modules.rst +++ b/docs/source/modules.rst @@ -1,8 +1,8 @@ -simopt -====== - -.. toctree:: - :maxdepth: 4 - - simopt - test +simopt +====== + +.. toctree:: + :maxdepth: 4 + + simopt + test diff --git a/docs/neldmd.rst b/docs/source/neldmd.rst similarity index 97% rename from docs/neldmd.rst rename to docs/source/neldmd.rst index 9b19e82a1..341a6550b 100644 --- a/docs/neldmd.rst +++ b/docs/source/neldmd.rst @@ -1,66 +1,66 @@ -Solver: Nelder-Mead (NELDMD) -============================ - -Description: ------------- -The algorithm maintains a simplex of points that moves around the feasible -region according to certain geometric operations: reflection, expansion, -scontraction, and shrinking. - -Modifications & Implementation: -------------------------------- -Initial (dimension + 1) points: -Include the initial solution from the model. Generate the remaining points using the .get_random_solution() method provided by the model. If there are box constraints, then the remaining points are instead generated by taking the initial solution and shifting it in a different dimension for each point by some value; the value is a fraction of the distance between the bounds. The direction of shift is towards smaller for minimization and larger for maximization unless it is out of bounds, for which the opposite direction is tried. If neither direction produces a valid solution, then that dimension is set to the lower bound for minimization or upper bound for maximization problems. - -Box constraints: -Nelder-Mead checks for box constraints in the solver and modifies the parts of a solution that go out of bounds by setting them to their respective closest bound. For example, if a tentative solution is (2,4) and the upper bound is (3,3), then the point is modified to (2,3). Additionally, if the reflected point goes out of bounds, all the points will be shrinked towards the best point. - -Scope: ------- -* objective_type: single - -* constraint_type: box - -* variable_type: continuous - -Solver Factors: ---------------- -* crn_across_solns: Use CRN across solutions? - - * Default: True - -* r: Number of replications taken at each solution. - - * Default: 30 - -* alpha: Reflection coefficient > 0. - - * Default: 1.0 - -* gammap: Expansion coefficient > 1. - - * Default: 2.0 - -* betap: Contraction coefficient > 0, < 1. - - * Default: 0.5 - -* delta: Shrink factor > 0, < 1. - - * Default: 0.5 - -* sensitivity: Shrinking scale for bounds to avoid floating and/or rounding errors. - - * Default: :math:`10^{-7}` - -* initial_spread: Fraction of the distance between bounds used to select initial points. - - * Default: 0.1 - - -References: -=========== -This solver is adapted from the article Russell R. Barton and John S. Ivey, Jr., (1996). -Nelder-Mead Simplex Modifications for Simulation Optimization. -*Management Science*, 42(7):954-973. +Solver: Nelder-Mead (NELDMD) +============================ + +Description: +------------ +The algorithm maintains a simplex of points that moves around the feasible +region according to certain geometric operations: reflection, expansion, +scontraction, and shrinking. + +Modifications & Implementation: +------------------------------- +Initial (dimension + 1) points: +Include the initial solution from the model. Generate the remaining points using the .get_random_solution() method provided by the model. If there are box constraints, then the remaining points are instead generated by taking the initial solution and shifting it in a different dimension for each point by some value; the value is a fraction of the distance between the bounds. The direction of shift is towards smaller for minimization and larger for maximization unless it is out of bounds, for which the opposite direction is tried. If neither direction produces a valid solution, then that dimension is set to the lower bound for minimization or upper bound for maximization problems. + +Box constraints: +Nelder-Mead checks for box constraints in the solver and modifies the parts of a solution that go out of bounds by setting them to their respective closest bound. For example, if a tentative solution is (2,4) and the upper bound is (3,3), then the point is modified to (2,3). Additionally, if the reflected point goes out of bounds, all the points will be shrinked towards the best point. + +Scope: +------ +* objective_type: single + +* constraint_type: box + +* variable_type: continuous + +Solver Factors: +--------------- +* crn_across_solns: Use CRN across solutions? + + * Default: True + +* r: Number of replications taken at each solution. + + * Default: 30 + +* alpha: Reflection coefficient > 0. + + * Default: 1.0 + +* gammap: Expansion coefficient > 1. + + * Default: 2.0 + +* betap: Contraction coefficient > 0, < 1. + + * Default: 0.5 + +* delta: Shrink factor > 0, < 1. + + * Default: 0.5 + +* sensitivity: Shrinking scale for bounds to avoid floating and/or rounding errors. + + * Default: :math:`10^{-7}` + +* initial_spread: Fraction of the distance between bounds used to select initial points. + + * Default: 0.1 + + +References: +=========== +This solver is adapted from the article Russell R. Barton and John S. Ivey, Jr., (1996). +Nelder-Mead Simplex Modifications for Simulation Optimization. +*Management Science*, 42(7):954-973. (https://pubsonline.informs.org/doi/abs/10.1287/mnsc.42.7.954) \ No newline at end of file diff --git a/docs/network.rst b/docs/source/network.rst similarity index 97% rename from docs/network.rst rename to docs/source/network.rst index 66f42de0b..aef20c205 100644 --- a/docs/network.rst +++ b/docs/source/network.rst @@ -1,110 +1,110 @@ -Model: Network Queueing System Design (Network) -=============================================== - -Description: ------------- -This model represents a communication system where arriving messages are routed through a network based on chosen routing percentages. There are :math:`N` random messages that arrive following a Poisson process with a rate of :math:`λ` that need to go to a particular destination, and there are :math:`n` networks available to process these messages. When a message arrives there is a :math:`p_i%` chance that it will be processed by network :math:`i`. The per message processing cost is :math:`c_1, c_2,..., c_i` depending on which network the message is routed through. It also takes time for a message to go through a network. This transit time is denoted by :math:`S_i` for each network :math:`i` and :math:`S_i` follows a triangular distribution with lower limit :math:`a_i`, upper limit :math:`b_i`, and mode :math:`c_i`. Each network behaves like a single-server queue with first-in-first-out service discipline.There is a cost for the length of time a message spends in network :math:`i` measured by :math:`c_i` per unit of time. - -Sources of Randomness: ----------------------- - 1. Interarrival time of a message. - 2. The network a message is routed to. - 3. The transit time of a message; depends on the network. - -Model Factors: --------------- -* process_prob: Probability that a message will go through a particular network i. - - * Default: [0.1, 0.1, 0.1, 0.1, 0.1, 0.1, 0.1, 0.1, 0.1, 0.1] - -* cost_process: Message processing cost of network i. - - * Default: [1, 1/2, 1/3, 1/4, 1/5, 1/6, 1/7, 1/8, 1/9, 1/10] - -* cost_time: Cost for the length of time a message spends in a network i per unit of time. - - * Default: [0.005, 0.005, 0.005, 0.005, 0.005, 0.005, 0.005, 0.005, 0.005, 0.005] - -* mode_transit_time: Mode time of transit for network i following a triangular distribution. - - * Default: [1, 2, 3, 4, 5, 6, 7, 8, 9, 10] - -* lower_limits_transit_time: Lower limits for the triangular distribution for the transit time. - - * Default: [0.5, 1.5, 2.5, 3.5, 4.5, 5.5, 6.5, 7.5, 8.5, 9.5] - -* upper_limits_transit_time: Upper limits for the triangular distribution for the transit time. - - * Default: [1.5, 2.5, 3.5, 4.5, 5.5, 6.5, 7.5, 8.5, 9.5, 10.5] - -* arrival_rate: Arrival rate of messages following a Poisson process. - - * Default: 1 - -* n_messages: Number of messages that arrive and need to be routed. - - * Default: 1000 - -* n_networks: Number of networks. - - * Default: 10 - - -Responses: ----------- -* total_cost: Total cost spent to route and process all messages. - - -References: -=========== -Barton, R. R., & Meckesheimer, M. (2006). Metamodel-Based Simulation Optimization. -S.G. Henderson and B.L. Nelson (Eds.), Handbook in OR & MS, Vol. 13. - -Optimization Problem: Minimize Total Cost (NETWORK-1) -======================================================== - -Decision Variables: -------------------- -* process_prob - -Objectives: ------------ -The objective is to minimize total costs, the sum of time costs and network costs for all messages. - -Constraints: ------------- -* :math:`0 \le p_i \le 1` for all :math:`i = 1, 2, ..., n` -* :math:`\sum_{i=1}^n p_i = 1` - -:math:`p_1, p_2,..., p_n \in [0, 1]` are the routing probabilities. - -Problem Factors: ----------------- -* initial_solution: Initial solution from which solvers start. - - * Default: [0.1, 0.1, 0.1, 0.1, 0.1, 0.1, 0.1, 0.1, 0.1, 0.1] - -* budget: Max # of replications for a solver to take. - - * Default: 1000 - -Fixed Model Factors: --------------------- -N/A - -Starting Solution: ------------------- -* process_prob: [0.1, 0.1, 0.1, 0.1, 0.1, 0.1, 0.1, 0.1, 0.1, 0.1] - - -Random Solutions: ------------------- -Generate allocations uniformly at random from the set of vectors of length equal to the number of networks whose values are greater than 0 and less than 1. - -Optimal Solution: ------------------ -Unknown - -Optimal Objective Function Value: ---------------------------------- -Unknown +Model: Network Queueing System Design (Network) +=============================================== + +Description: +------------ +This model represents a communication system where arriving messages are routed through a network based on chosen routing percentages. There are :math:`N` random messages that arrive following a Poisson process with a rate of :math:`λ` that need to go to a particular destination, and there are :math:`n` networks available to process these messages. When a message arrives there is a :math:`p_i%` chance that it will be processed by network :math:`i`. The per message processing cost is :math:`c_1, c_2,..., c_i` depending on which network the message is routed through. It also takes time for a message to go through a network. This transit time is denoted by :math:`S_i` for each network :math:`i` and :math:`S_i` follows a triangular distribution with lower limit :math:`a_i`, upper limit :math:`b_i`, and mode :math:`c_i`. Each network behaves like a single-server queue with first-in-first-out service discipline.There is a cost for the length of time a message spends in network :math:`i` measured by :math:`c_i` per unit of time. + +Sources of Randomness: +---------------------- + 1. Interarrival time of a message. + 2. The network a message is routed to. + 3. The transit time of a message; depends on the network. + +Model Factors: +-------------- +* process_prob: Probability that a message will go through a particular network i. + + * Default: [0.1, 0.1, 0.1, 0.1, 0.1, 0.1, 0.1, 0.1, 0.1, 0.1] + +* cost_process: Message processing cost of network i. + + * Default: [1, 1/2, 1/3, 1/4, 1/5, 1/6, 1/7, 1/8, 1/9, 1/10] + +* cost_time: Cost for the length of time a message spends in a network i per unit of time. + + * Default: [0.005, 0.005, 0.005, 0.005, 0.005, 0.005, 0.005, 0.005, 0.005, 0.005] + +* mode_transit_time: Mode time of transit for network i following a triangular distribution. + + * Default: [1, 2, 3, 4, 5, 6, 7, 8, 9, 10] + +* lower_limits_transit_time: Lower limits for the triangular distribution for the transit time. + + * Default: [0.5, 1.5, 2.5, 3.5, 4.5, 5.5, 6.5, 7.5, 8.5, 9.5] + +* upper_limits_transit_time: Upper limits for the triangular distribution for the transit time. + + * Default: [1.5, 2.5, 3.5, 4.5, 5.5, 6.5, 7.5, 8.5, 9.5, 10.5] + +* arrival_rate: Arrival rate of messages following a Poisson process. + + * Default: 1 + +* n_messages: Number of messages that arrive and need to be routed. + + * Default: 1000 + +* n_networks: Number of networks. + + * Default: 10 + + +Responses: +---------- +* total_cost: Total cost spent to route and process all messages. + + +References: +=========== +Barton, R. R., & Meckesheimer, M. (2006). Metamodel-Based Simulation Optimization. +S.G. Henderson and B.L. Nelson (Eds.), Handbook in OR & MS, Vol. 13. + +Optimization Problem: Minimize Total Cost (NETWORK-1) +======================================================== + +Decision Variables: +------------------- +* process_prob + +Objectives: +----------- +The objective is to minimize total costs, the sum of time costs and network costs for all messages. + +Constraints: +------------ +* :math:`0 \le p_i \le 1` for all :math:`i = 1, 2, ..., n` +* :math:`\sum_{i=1}^n p_i = 1` + +:math:`p_1, p_2,..., p_n \in [0, 1]` are the routing probabilities. + +Problem Factors: +---------------- +* initial_solution: Initial solution from which solvers start. + + * Default: [0.1, 0.1, 0.1, 0.1, 0.1, 0.1, 0.1, 0.1, 0.1, 0.1] + +* budget: Max # of replications for a solver to take. + + * Default: 1000 + +Fixed Model Factors: +-------------------- +N/A + +Starting Solution: +------------------ +* process_prob: [0.1, 0.1, 0.1, 0.1, 0.1, 0.1, 0.1, 0.1, 0.1, 0.1] + + +Random Solutions: +------------------ +Generate allocations uniformly at random from the set of vectors of length equal to the number of networks whose values are greater than 0 and less than 1. + +Optimal Solution: +----------------- +Unknown + +Optimal Objective Function Value: +--------------------------------- +Unknown diff --git a/docs/paramesti.rst b/docs/source/paramesti.rst similarity index 96% rename from docs/paramesti.rst rename to docs/source/paramesti.rst index f1b996be9..62f489c0c 100644 --- a/docs/paramesti.rst +++ b/docs/source/paramesti.rst @@ -1,89 +1,89 @@ -Model: Parameter Estimation (PARAMESTI) -======================================= - -Description: ------------- -A model that simulates maximum likelihood estimation for the parameters of -a two-dimensional gamma distribution. - -Say a simulation generates output data :math:`{Y_j}`, :math:`Y_j \in [0, \infty] \times [0, \infty]`, -that are i.i.d and known to come from a distribution with the two-dimensional density function - -.. math:: f(y1, y2; x^*) = \frac{e^{-y1} y_1^{x^*_1 y_2 - 1}{\Gamma(x^*_1 y_2)} \frac{e^{-y2} y_2^{x^*_2 - 1}{\Gamma(x^*_2)}, y1, y2 > 0, - -where :math:`x^* ≡ (x^*_1, x^*_2)`` is the unknown vector of parameters. - -Noting that :math:`x_star` maximizes the function - -.. math:: g(x) = E [log (f(Y ; x))] = \int_0^\infty \log (f(y; x)) f(y; x^*)dy, - -and that - -.. math:: G_m(x) = \frac{1}{m} \sum_{j=1}^m \log(f(Y_j ; x)) - -is a consistent estimator of :math:`g(x)`. -Observations are generated from the distribution specified by a given :math:`x_star`. - -Sources of Randomness: ----------------------- -y is a 2-D vector that contributes randomness. Both elements of y are gamma random variables. - -Model Factors: --------------- -* x_star: the unknown 2-D parameter that maximizes the expected log likelihood function. - - * Default: [2, 5] - -* x: a 2-D variable in the probability density function. - - * Default: [1, 1] - -Respones: ---------- -* loglik: log likelihood of the pdf. - -References: -=========== -This model is designed by Raghu Pasupathy (Virginia Tech) and Shane G. Henderson (Cornell) in 2007. - - -Optimization Problem: Max Log Likelihood (ParamEstiMaxLogLik) -============================================================= - -Decision Variables: -------------------- -* x - -Objectives: ------------ -Minimize the log likelihood of a 2-D gamma random variable. - -Constraints: ------------- -x is in the square (0, 10) × (0, 10). - -Problem Factors: ----------------- -* budget: Maximum number of replications for a solver to take. - - * Default: 1000 - -Fixed Model Factors: --------------------- -N/A - -Starting Solution: ------------------- -* x: [1, 1] - -Random Solutions: ------------------ -Generate :math:`x` i.i.d. uniformly in the square (0, 10) × (0, 10). - -Optimal Solution: ------------------ -x = [2, 5] - -Optimal Objective Function Value: ---------------------------------- -Known, but not evaluated. +Model: Parameter Estimation (PARAMESTI) +======================================= + +Description: +------------ +A model that simulates maximum likelihood estimation for the parameters of +a two-dimensional gamma distribution. + +Say a simulation generates output data :math:`{Y_j}`, :math:`Y_j \in [0, \infty] \times [0, \infty]`, +that are i.i.d and known to come from a distribution with the two-dimensional density function + +.. math:: f(y1, y2; x^*) = \frac{e^{-y1} y_1^{x^*_1 y_2 - 1}{\Gamma(x^*_1 y_2)} \frac{e^{-y2} y_2^{x^*_2 - 1}{\Gamma(x^*_2)}, y1, y2 > 0, + +where :math:`x^* ≡ (x^*_1, x^*_2)`` is the unknown vector of parameters. + +Noting that :math:`x_star` maximizes the function + +.. math:: g(x) = E [log (f(Y ; x))] = \int_0^\infty \log (f(y; x)) f(y; x^*)dy, + +and that + +.. math:: G_m(x) = \frac{1}{m} \sum_{j=1}^m \log(f(Y_j ; x)) + +is a consistent estimator of :math:`g(x)`. +Observations are generated from the distribution specified by a given :math:`x_star`. + +Sources of Randomness: +---------------------- +y is a 2-D vector that contributes randomness. Both elements of y are gamma random variables. + +Model Factors: +-------------- +* x_star: the unknown 2-D parameter that maximizes the expected log likelihood function. + + * Default: [2, 5] + +* x: a 2-D variable in the probability density function. + + * Default: [1, 1] + +Respones: +--------- +* loglik: log likelihood of the pdf. + +References: +=========== +This model is designed by Raghu Pasupathy (Virginia Tech) and Shane G. Henderson (Cornell) in 2007. + + +Optimization Problem: Max Log Likelihood (ParamEstiMaxLogLik) +============================================================= + +Decision Variables: +------------------- +* x + +Objectives: +----------- +Minimize the log likelihood of a 2-D gamma random variable. + +Constraints: +------------ +x is in the square (0, 10) × (0, 10). + +Problem Factors: +---------------- +* budget: Maximum number of replications for a solver to take. + + * Default: 1000 + +Fixed Model Factors: +-------------------- +N/A + +Starting Solution: +------------------ +* x: [1, 1] + +Random Solutions: +----------------- +Generate :math:`x` i.i.d. uniformly in the square (0, 10) × (0, 10). + +Optimal Solution: +----------------- +x = [2, 5] + +Optimal Objective Function Value: +--------------------------------- +Known, but not evaluated. diff --git a/docs/prodsys.rst b/docs/source/prodsys.rst similarity index 96% rename from docs/prodsys.rst rename to docs/source/prodsys.rst index 489aed8ec..ec9f50298 100644 --- a/docs/prodsys.rst +++ b/docs/source/prodsys.rst @@ -1,149 +1,149 @@ -Model: Production System (ProdSys) -================================== - -Description: ------------- -Let :math:`G = (V, A)` be a production network with a set of nodes :math:`V = {1, 2,..., n}`. :math:`num_products` -different final products correspond to the nodes with outdegree 0. Each node in :math:`V` represents a state of -the product while each arc denotes the process of transforming one intermediate product to another. - -Every transformation process uses one of the :math:`num_machines` machines. All processing times are random with given distributions, -and orders for each of the :math:`num_products` final products are also random and arrive at random intervals. -Assume that the time horizon is :math:`H`, and that the available sets of raw material equals -the expected value of the total demand of all :math:`num_products` final products. - -Sources of Randomness: ----------------------- -3 sources of randomness exist: - -1. Normally distributed order inter-arrival times. - -2. Product type of the order. - -3. Normally distributed machine processing times. - -Model Factors: --------------- -* :math:`num_products`: Number of products. - - * Default: 3 - -* :math:`interarrival_time_mean`: Mean of interarrival times of orders for each product. - - * Default: 30 - -* :math:`interarrival_time_stdev`: Standard deviation of interarrival times of orders for each product. - - * Default: 5 - -* :math:`num_machines`: Number of machines. - - * Default: 2 - -* :math:`num_edges`: Number of edges. - - * Default: 6 - -* :math:`total_inventory`: Total inventory. - - * Default: 200 - -* :math:`interm_product`: Product quantities to be processed ahead of time; number of intermediate products presently at each node. - - * Default: [200, 0, 0, 0, 0, 0] - -* :math:`routing_layout`: Layout matrix. List of edges sequences for each product type. - - * Default: [[1, 2], - [1, 3], - [2, 4], - [2, 5], - [3, 5], - [3, 6]] - -* :math:`machine_layout`: List of machines. Each element is the index for the machine that processes the task on each edge. - - * Default: [1, 2, 2, 2, 1, 1] - -* :math:`processing_time_mean`: Mean of normally distributed processing times. Each element is associated with a task (edge). - * Default: [4, 3, 5, 4, 4, 3] - -* :math:`processing_time_stdev`: Standard deviation of normally distributed processing times. Each element is associated with a task (edge). - - * Default: [1, 1, 2, 1, 1, 1] - -* :math:`product_batch_prob`: Batch order probabilities of each product. - - * Default: [0.5, 0.35, 0.15] - -* :math:`time_horizon`: Time horizon. - - * Default: 600 - -* :math:`batch`: Batch size. - - * Default: 10 - -Responses: ----------- -* :math:`avg_lead_time`: Average lead time. - -* :math:`service_level`: Service level. - - -References: -=========== -This model is adapted from the article Azadivar, F., Shu, J., & Ahmad, M. (1996). Simulation Optimization in Strategic Location of Semi-Finished Products in a Pull-Type Production System. -*Proceedings of the 1996 Winter Simulation Conference (WSC)*, 1123-1128. - - - -Optimization Problem: Minimize Lead Time (ProdSysMinLeadTime) -============================================================= -Our objective is to minimize the expected lead time, -while satisfying a tolerable service level, :math:`b` with high probability :math:`1 − α`. - -Decision Variables: -------------------- -* :math:`interm_products` - -Objectives: ------------ -Minimize expected :math:`avg_lead_time`. - -Constraints: ------------- -interm_products must be non-negative vector of length equal to number of nodes. -1 deterministic constraint: interm_products must sum to total inventory. -1 stochastic constraint: :math:`P[{service_level} ≥ b] ≥ 1 − α`. - -Problem Factors: ----------------- -* :math:`alpha`: Risk level parameter. - - * Default: 0.10 - -* :math:`min_sslevel`: Minimum tolerable service level (b). - - * Default: 0.5 - -Fixed Model Factors: --------------------- -None - -Starting Solution: ------------------- -* interm_product: [200, 0, 0, 0, 0, 0] - -Random Solutions: ------------------- -Generate initial inventory vectors uniformly at random from the set of vectors (of length equal to the number of nodes) whose values sum to the total inventory. - - -Optimal Solution: ------------------ -N/A - -Optimal Objective Function Value: ---------------------------------- -N/A +Model: Production System (ProdSys) +================================== + +Description: +------------ +Let :math:`G = (V, A)` be a production network with a set of nodes :math:`V = {1, 2,..., n}`. :math:`num_products` +different final products correspond to the nodes with outdegree 0. Each node in :math:`V` represents a state of +the product while each arc denotes the process of transforming one intermediate product to another. + +Every transformation process uses one of the :math:`num_machines` machines. All processing times are random with given distributions, +and orders for each of the :math:`num_products` final products are also random and arrive at random intervals. +Assume that the time horizon is :math:`H`, and that the available sets of raw material equals +the expected value of the total demand of all :math:`num_products` final products. + +Sources of Randomness: +---------------------- +3 sources of randomness exist: + +1. Normally distributed order inter-arrival times. + +2. Product type of the order. + +3. Normally distributed machine processing times. + +Model Factors: +-------------- +* :math:`num_products`: Number of products. + + * Default: 3 + +* :math:`interarrival_time_mean`: Mean of interarrival times of orders for each product. + + * Default: 30 + +* :math:`interarrival_time_stdev`: Standard deviation of interarrival times of orders for each product. + + * Default: 5 + +* :math:`num_machines`: Number of machines. + + * Default: 2 + +* :math:`num_edges`: Number of edges. + + * Default: 6 + +* :math:`total_inventory`: Total inventory. + + * Default: 200 + +* :math:`interm_product`: Product quantities to be processed ahead of time; number of intermediate products presently at each node. + + * Default: [200, 0, 0, 0, 0, 0] + +* :math:`routing_layout`: Layout matrix. List of edges sequences for each product type. + + * Default: [[1, 2], + [1, 3], + [2, 4], + [2, 5], + [3, 5], + [3, 6]] + +* :math:`machine_layout`: List of machines. Each element is the index for the machine that processes the task on each edge. + + * Default: [1, 2, 2, 2, 1, 1] + +* :math:`processing_time_mean`: Mean of normally distributed processing times. Each element is associated with a task (edge). + * Default: [4, 3, 5, 4, 4, 3] + +* :math:`processing_time_stdev`: Standard deviation of normally distributed processing times. Each element is associated with a task (edge). + + * Default: [1, 1, 2, 1, 1, 1] + +* :math:`product_batch_prob`: Batch order probabilities of each product. + + * Default: [0.5, 0.35, 0.15] + +* :math:`time_horizon`: Time horizon. + + * Default: 600 + +* :math:`batch`: Batch size. + + * Default: 10 + +Responses: +---------- +* :math:`avg_lead_time`: Average lead time. + +* :math:`service_level`: Service level. + + +References: +=========== +This model is adapted from the article Azadivar, F., Shu, J., & Ahmad, M. (1996). Simulation Optimization in Strategic Location of Semi-Finished Products in a Pull-Type Production System. +*Proceedings of the 1996 Winter Simulation Conference (WSC)*, 1123-1128. + + + +Optimization Problem: Minimize Lead Time (ProdSysMinLeadTime) +============================================================= +Our objective is to minimize the expected lead time, +while satisfying a tolerable service level, :math:`b` with high probability :math:`1 − α`. + +Decision Variables: +------------------- +* :math:`interm_products` + +Objectives: +----------- +Minimize expected :math:`avg_lead_time`. + +Constraints: +------------ +interm_products must be non-negative vector of length equal to number of nodes. +1 deterministic constraint: interm_products must sum to total inventory. +1 stochastic constraint: :math:`P[{service_level} ≥ b] ≥ 1 − α`. + +Problem Factors: +---------------- +* :math:`alpha`: Risk level parameter. + + * Default: 0.10 + +* :math:`min_sslevel`: Minimum tolerable service level (b). + + * Default: 0.5 + +Fixed Model Factors: +-------------------- +None + +Starting Solution: +------------------ +* interm_product: [200, 0, 0, 0, 0, 0] + +Random Solutions: +------------------ +Generate initial inventory vectors uniformly at random from the set of vectors (of length equal to the number of nodes) whose values sum to the total inventory. + + +Optimal Solution: +----------------- +N/A + +Optimal Objective Function Value: +--------------------------------- +N/A diff --git a/docs/randomsearch.rst b/docs/source/randomsearch.rst similarity index 96% rename from docs/randomsearch.rst rename to docs/source/randomsearch.rst index f87234d95..56c6cfee5 100644 --- a/docs/randomsearch.rst +++ b/docs/source/randomsearch.rst @@ -1,38 +1,38 @@ -Solver: Random Search (RNDSRCH) -=============================== - -Description: ------------- -Randomly sample solutions from the feasible region and use a fixed number of replications at each solution. The sampling distribution is specified inside each problem class in **get_random_solution**. - -Modifications & Implementation: -------------------------------- -The new random solutions maintain the type of each variable based on the sampling distributions that are discrete for integer decisions and otherwise continuous. - -Scope: ------- -* objective_type: single - -* constraint_type: stochastic - -* variable_type: mixed - -* gradient_observations: not available - -Solver Factors: ---------------- -* crn_across_solns: Use CRN across solutions? - - * Default: True - -* sample_size: Sample size per solution > 1. - - * Default: 10 - - -References: -=========== -This solver is adapted from the article Chia, Y.L. and Glynn, P.W., (2013). -Limit Theorems for Simulation-Based Optimization via Random Search. -*ACM Transactions on Modeling and Computer Simulation (TOMACS)*, 23(3), pp.1-18. +Solver: Random Search (RNDSRCH) +=============================== + +Description: +------------ +Randomly sample solutions from the feasible region and use a fixed number of replications at each solution. The sampling distribution is specified inside each problem class in **get_random_solution**. + +Modifications & Implementation: +------------------------------- +The new random solutions maintain the type of each variable based on the sampling distributions that are discrete for integer decisions and otherwise continuous. + +Scope: +------ +* objective_type: single + +* constraint_type: stochastic + +* variable_type: mixed + +* gradient_observations: not available + +Solver Factors: +--------------- +* crn_across_solns: Use CRN across solutions? + + * Default: True + +* sample_size: Sample size per solution > 1. + + * Default: 10 + + +References: +=========== +This solver is adapted from the article Chia, Y.L. and Glynn, P.W., (2013). +Limit Theorems for Simulation-Based Optimization via Random Search. +*ACM Transactions on Modeling and Computer Simulation (TOMACS)*, 23(3), pp.1-18. (https://dl.acm.org/doi/abs/10.1145/2499913.2499915) \ No newline at end of file diff --git a/docs/rmitd.rst b/docs/source/rmitd.rst similarity index 96% rename from docs/rmitd.rst rename to docs/source/rmitd.rst index 7bdad0be1..8a8d903b4 100644 --- a/docs/rmitd.rst +++ b/docs/source/rmitd.rst @@ -1,131 +1,131 @@ -Model: Multi-Stage Revenue Management with Inter-Temporal Dependence (RMITD) -============================================================================ - -Description: ------------- - -Consider the following inventory system: A businessperson initially purchases -:math:`b` units of a product to sell to customers over a fixed time horizon. -In the first period, a businessperson receives a certain demand for units at a -low price :math:`p_{low}`. The businessperson decision can choose how many units -to sell right now. The businessperson may wish to reserve some units for -customers arriving later who are willing to pay more for the product. The number -of units reserved for the start of period :math:`t` is denoted by :math:`r_t`. This -process of observing demand and choosing how many units to sell is repeated over -:math:`T` time periods. In order to make wise decisions about how much inventory -to reserve in each time period, the businessperson must consider future demand for -the product. - -The demand in period :math:`t` is denoted by :math:`D_t = μ_tXY_t` where :math:`X` -has a gamma distribution with parameters :math:`k > 0` and :math:`θ > 0` such that -it has mean :math:`kθ = 1` and standard deviation :math:`{\sqrt{k}}θ = 1/ {\sqrt{k}}.` -:math:` Y_1, . . . , Y_T` are i.i.d. exponential with mean 1 and -:math:`μ_t` are positive constants for all :math:`t`. - -Sources of Randomness: ----------------------- -Two sources of randomness are used to generate the :math:`X`s and :math:`Y`s that -form demands. - -Model Factors: --------------- -* Time Horizon (T): Period of time that is considered. - - * Default: 3 - -* Prices: Prices for each period. - - * Default: (100, 300, 400) - -* Demand Mean (μ): Mean demand for each period. - - * Default: (50, 20, 30) - -* Cost (c): Cost per unit of capacity at :math:`t = 0`. - - * Default: 80 - -* Gamma Shape (k): Shape parameter of gamma distribution. - - * Default: 1 - -* Gamma Scale (θ): Scale parameter of gamma distribution. - - * Default: 1 - -* Initial Inventory (b): Initial inventory. - - * Default: 100 - -* Reservation Quantity (r): Inventory to reserve going into periods :math:`2, 3, ..., T`. - - * Default: :math:`r_2 = 50`, :math:`r_3 = 30`. - - -Responses: ----------- - -* Revenue: Total revenue of given model - -References: -=========== -This example is adapted (almost verbatim) from test problem 2 by Prof. J.M. Harrison for class OIT 603 -at Stanford University. (https://www.gsb.stanford.edu/faculty-research/faculty/j-michael-harrison) - - -Optimization Problem: Maximize Total Revenue -============================================ - -Decision Variables: -------------------- - -* Initial Inventory (b) - -* Reservation Quantities (:math:`r_t`) - -Objectives: ------------ - -Maximize total revenue. - -Constraints: ------------- - -The reserve quantities are decreasing and less than the initial capacity, i.e., -:math:`b >= r_2 >= r_3` - -Problem Factors: ----------------- - -* Budget: Max # of replications for a solver to take. - - * Default: 10000 - -Fixed Model Factors: --------------------- - -* N/A - -Starting Solution: ------------------- - -* :math:`b = 100` - -* :math:`r_2 = 50` - -* :math:`r_3 = 30` - -Random Solutions: ------------------ - -If multiple solutions are needed for Reservation Quantity (r), use :math:`r_2` ∼ Uniform(40,60) and :math:`r_3` ∼ Uniform(20,40). - -Optimal Solution: ------------------ - -Unknown - -Optimal Objective Function Value: ---------------------------------- - -Unknown +Model: Multi-Stage Revenue Management with Inter-Temporal Dependence (RMITD) +============================================================================ + +Description: +------------ + +Consider the following inventory system: A businessperson initially purchases +:math:`b` units of a product to sell to customers over a fixed time horizon. +In the first period, a businessperson receives a certain demand for units at a +low price :math:`p_{low}`. The businessperson decision can choose how many units +to sell right now. The businessperson may wish to reserve some units for +customers arriving later who are willing to pay more for the product. The number +of units reserved for the start of period :math:`t` is denoted by :math:`r_t`. This +process of observing demand and choosing how many units to sell is repeated over +:math:`T` time periods. In order to make wise decisions about how much inventory +to reserve in each time period, the businessperson must consider future demand for +the product. + +The demand in period :math:`t` is denoted by :math:`D_t = μ_tXY_t` where :math:`X` +has a gamma distribution with parameters :math:`k > 0` and :math:`θ > 0` such that +it has mean :math:`kθ = 1` and standard deviation :math:`{\sqrt{k}}θ = 1/ {\sqrt{k}}.` +:math:` Y_1, . . . , Y_T` are i.i.d. exponential with mean 1 and +:math:`μ_t` are positive constants for all :math:`t`. + +Sources of Randomness: +---------------------- +Two sources of randomness are used to generate the :math:`X`s and :math:`Y`s that +form demands. + +Model Factors: +-------------- +* Time Horizon (T): Period of time that is considered. + + * Default: 3 + +* Prices: Prices for each period. + + * Default: (100, 300, 400) + +* Demand Mean (μ): Mean demand for each period. + + * Default: (50, 20, 30) + +* Cost (c): Cost per unit of capacity at :math:`t = 0`. + + * Default: 80 + +* Gamma Shape (k): Shape parameter of gamma distribution. + + * Default: 1 + +* Gamma Scale (θ): Scale parameter of gamma distribution. + + * Default: 1 + +* Initial Inventory (b): Initial inventory. + + * Default: 100 + +* Reservation Quantity (r): Inventory to reserve going into periods :math:`2, 3, ..., T`. + + * Default: :math:`r_2 = 50`, :math:`r_3 = 30`. + + +Responses: +---------- + +* Revenue: Total revenue of given model + +References: +=========== +This example is adapted (almost verbatim) from test problem 2 by Prof. J.M. Harrison for class OIT 603 +at Stanford University. (https://www.gsb.stanford.edu/faculty-research/faculty/j-michael-harrison) + + +Optimization Problem: Maximize Total Revenue +============================================ + +Decision Variables: +------------------- + +* Initial Inventory (b) + +* Reservation Quantities (:math:`r_t`) + +Objectives: +----------- + +Maximize total revenue. + +Constraints: +------------ + +The reserve quantities are decreasing and less than the initial capacity, i.e., +:math:`b >= r_2 >= r_3` + +Problem Factors: +---------------- + +* Budget: Max # of replications for a solver to take. + + * Default: 10000 + +Fixed Model Factors: +-------------------- + +* N/A + +Starting Solution: +------------------ + +* :math:`b = 100` + +* :math:`r_2 = 50` + +* :math:`r_3 = 30` + +Random Solutions: +----------------- + +If multiple solutions are needed for Reservation Quantity (r), use :math:`r_2` ∼ Uniform(40,60) and :math:`r_3` ∼ Uniform(20,40). + +Optimal Solution: +----------------- + +Unknown + +Optimal Objective Function Value: +--------------------------------- + +Unknown diff --git a/docs/san.rst b/docs/source/san.rst similarity index 96% rename from docs/san.rst rename to docs/source/san.rst index ee8bf0324..e32b1aab4 100644 --- a/docs/san.rst +++ b/docs/source/san.rst @@ -1,98 +1,98 @@ -Model: Stochastic Activity Network (SAN) -======================================== - -Description: ------------- -Consider a stochastic activity network (SAN) where each arc :math:`i` -is associated with a task with random duration :math:`X_i`. Task durations -are independent. SANs are also known as PERT networks and are used in planning -large-scale projects. - -An example SAN with 13 arcs is given in the following figure: - -.. image:: san.PNG - :alt: The SAN diagram has failed to display - :width: 500 - -Sources of Randomness: ----------------------- -1. Task durations are exponentially distributed with mean :math:`\theta_i`. - -Model Factors: --------------- -* num_nodes: Number of nodes. - - * Default: 9 - -* arcs: List of arcs. - - * Default: [(1, 2), (1, 3), (2, 3), (2, 4), (2, 6), (3, 6), (4, 5), - (4, 7), (5, 6), (5, 8), (6, 9), (7, 8), (8, 9)] - -* arc_means: Mean task durations for each arc. - - * Default: (1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1) - -Responses: ----------- -* longest_path_length: Length/duration of the longest path. - - -References: -=========== -This model is adapted from Avramidis, A.N., Wilson, J.R. (1996). -Integrated variance reduction strategies for simulation. *Operations Research* 44, 327-346. -(https://pubsonline.informs.org/doi/abs/10.1287/opre.44.2.327) - -Optimization Problem: Minimize Longest Path Plus Penalty (SAN-1) -================================================================ - -Decision Variables: -------------------- -* arc_means - -Objectives: ------------ -Suppose that we can select :math:`\theta_i > 0` for each :math:`i`, -but there is an associated cost. In particular, we want to minimize :math:`ET(\theta) + f(\theta)`, -where :math:`T(\theta)` is the (random) duration of the longest path from :math:`a` -to :math:`i` and :math:`f(\theta) = \sum_{i=1}^{n}\theta_i^{-1}` where :math:`n` -is the number of arcs. - -The objective function is convex in :math:`\theta`. An IPA estimator of the gradient -is also given in the code. - -Constraints: ------------- -We require that :math:`theta_i > 0` for each :math:`i`. - -Problem Factors: ----------------- -* budget: Max # of replications for a solver to take. - - * Default: 10000 - -* arc_costs: Cost associated to each arc. - - * Default: (1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1) - -Fixed Model Factors: --------------------- -* N/A - -Starting Solution: ------------------- -* initial_solution: (8,) * 13 - -Random Solutions: ------------------ -Sample each arc mean uniformly from a lognormal distribution with -2.5- and 97.5-percentiles at 0.1 and 10 respectively. - -Optimal Solution: ------------------ -Unknown - -Optimal Objective Function Value: ---------------------------------- +Model: Stochastic Activity Network (SAN) +======================================== + +Description: +------------ +Consider a stochastic activity network (SAN) where each arc :math:`i` +is associated with a task with random duration :math:`X_i`. Task durations +are independent. SANs are also known as PERT networks and are used in planning +large-scale projects. + +An example SAN with 13 arcs is given in the following figure: + +.. image:: san.PNG + :alt: The SAN diagram has failed to display + :width: 500 + +Sources of Randomness: +---------------------- +1. Task durations are exponentially distributed with mean :math:`\theta_i`. + +Model Factors: +-------------- +* num_nodes: Number of nodes. + + * Default: 9 + +* arcs: List of arcs. + + * Default: [(1, 2), (1, 3), (2, 3), (2, 4), (2, 6), (3, 6), (4, 5), + (4, 7), (5, 6), (5, 8), (6, 9), (7, 8), (8, 9)] + +* arc_means: Mean task durations for each arc. + + * Default: (1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1) + +Responses: +---------- +* longest_path_length: Length/duration of the longest path. + + +References: +=========== +This model is adapted from Avramidis, A.N., Wilson, J.R. (1996). +Integrated variance reduction strategies for simulation. *Operations Research* 44, 327-346. +(https://pubsonline.informs.org/doi/abs/10.1287/opre.44.2.327) + +Optimization Problem: Minimize Longest Path Plus Penalty (SAN-1) +================================================================ + +Decision Variables: +------------------- +* arc_means + +Objectives: +----------- +Suppose that we can select :math:`\theta_i > 0` for each :math:`i`, +but there is an associated cost. In particular, we want to minimize :math:`ET(\theta) + f(\theta)`, +where :math:`T(\theta)` is the (random) duration of the longest path from :math:`a` +to :math:`i` and :math:`f(\theta) = \sum_{i=1}^{n}\theta_i^{-1}` where :math:`n` +is the number of arcs. + +The objective function is convex in :math:`\theta`. An IPA estimator of the gradient +is also given in the code. + +Constraints: +------------ +We require that :math:`theta_i > 0` for each :math:`i`. + +Problem Factors: +---------------- +* budget: Max # of replications for a solver to take. + + * Default: 10000 + +* arc_costs: Cost associated to each arc. + + * Default: (1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1) + +Fixed Model Factors: +-------------------- +* N/A + +Starting Solution: +------------------ +* initial_solution: (8,) * 13 + +Random Solutions: +----------------- +Sample each arc mean uniformly from a lognormal distribution with +2.5- and 97.5-percentiles at 0.1 and 10 respectively. + +Optimal Solution: +----------------- +Unknown + +Optimal Objective Function Value: +--------------------------------- Unknown \ No newline at end of file diff --git a/docs/simopt.models.rst b/docs/source/simopt.models.rst similarity index 94% rename from docs/simopt.models.rst rename to docs/source/simopt.models.rst index 9c6c89937..f4bd5da16 100644 --- a/docs/simopt.models.rst +++ b/docs/source/simopt.models.rst @@ -1,157 +1,157 @@ -simopt.models package -===================== - -Submodules ----------- - -simopt.models.amusementpark module ----------------------------------- - -.. automodule:: simopt.models.amusementpark - :members: - :undoc-members: - :show-inheritance: - -simopt.models.chessmm module ----------------------------- - -.. automodule:: simopt.models.chessmm - :members: - :undoc-members: - :show-inheritance: - -simopt.models.cntnv module --------------------------- - -.. automodule:: simopt.models.cntnv - :members: - :undoc-members: - :show-inheritance: - -simopt.models.contam module ---------------------------- - -.. automodule:: simopt.models.contam - :members: - :undoc-members: - :show-inheritance: - -simopt.models.dualsourcing module ---------------------------------- - -.. automodule:: simopt.models.dualsourcing - :members: - :undoc-members: - :show-inheritance: - -simopt.models.dynamnews module ------------------------------- - -.. automodule:: simopt.models.dynamnews - :members: - :undoc-members: - :show-inheritance: - -simopt.models.example module ----------------------------- - -.. automodule:: simopt.models.example - :members: - :undoc-members: - :show-inheritance: - -simopt.models.facilitysizing module ------------------------------------ - -.. automodule:: simopt.models.facilitysizing - :members: - :undoc-members: - :show-inheritance: - -simopt.models.fixedsan module ------------------------------ - -.. automodule:: simopt.models.fixedsan - :members: - :undoc-members: - :show-inheritance: - -simopt.models.hotel module --------------------------- - -.. automodule:: simopt.models.hotel - :members: - :undoc-members: - :show-inheritance: - -simopt.models.ironore module ----------------------------- - -.. automodule:: simopt.models.ironore - :members: - :undoc-members: - :show-inheritance: - -simopt.models.mm1queue module ------------------------------ - -.. automodule:: simopt.models.mm1queue - :members: - :undoc-members: - :show-inheritance: - -simopt.models.network module ----------------------------- - -.. automodule:: simopt.models.network - :members: - :undoc-members: - :show-inheritance: - -simopt.models.paramesti module ------------------------------- - -.. automodule:: simopt.models.paramesti - :members: - :undoc-members: - :show-inheritance: - -simopt.models.rmitd module --------------------------- - -.. automodule:: simopt.models.rmitd - :members: - :undoc-members: - :show-inheritance: - -simopt.models.san module ------------------------- - -.. automodule:: simopt.models.san - :members: - :undoc-members: - :show-inheritance: - -simopt.models.sscont module ---------------------------- - -.. automodule:: simopt.models.sscont - :members: - :undoc-members: - :show-inheritance: - -simopt.models.tableallocation module ------------------------------------- - -.. automodule:: simopt.models.tableallocation - :members: - :undoc-members: - :show-inheritance: - -Module contents ---------------- - -.. automodule:: simopt.models - :members: - :undoc-members: - :show-inheritance: +simopt.models package +===================== + +Submodules +---------- + +simopt.models.amusementpark module +---------------------------------- + +.. automodule:: simopt.models.amusementpark + :members: + :undoc-members: + :show-inheritance: + +simopt.models.chessmm module +---------------------------- + +.. automodule:: simopt.models.chessmm + :members: + :undoc-members: + :show-inheritance: + +simopt.models.cntnv module +-------------------------- + +.. automodule:: simopt.models.cntnv + :members: + :undoc-members: + :show-inheritance: + +simopt.models.contam module +--------------------------- + +.. automodule:: simopt.models.contam + :members: + :undoc-members: + :show-inheritance: + +simopt.models.dualsourcing module +--------------------------------- + +.. automodule:: simopt.models.dualsourcing + :members: + :undoc-members: + :show-inheritance: + +simopt.models.dynamnews module +------------------------------ + +.. automodule:: simopt.models.dynamnews + :members: + :undoc-members: + :show-inheritance: + +simopt.models.example module +---------------------------- + +.. automodule:: simopt.models.example + :members: + :undoc-members: + :show-inheritance: + +simopt.models.facilitysizing module +----------------------------------- + +.. automodule:: simopt.models.facilitysizing + :members: + :undoc-members: + :show-inheritance: + +simopt.models.fixedsan module +----------------------------- + +.. automodule:: simopt.models.fixedsan + :members: + :undoc-members: + :show-inheritance: + +simopt.models.hotel module +-------------------------- + +.. automodule:: simopt.models.hotel + :members: + :undoc-members: + :show-inheritance: + +simopt.models.ironore module +---------------------------- + +.. automodule:: simopt.models.ironore + :members: + :undoc-members: + :show-inheritance: + +simopt.models.mm1queue module +----------------------------- + +.. automodule:: simopt.models.mm1queue + :members: + :undoc-members: + :show-inheritance: + +simopt.models.network module +---------------------------- + +.. automodule:: simopt.models.network + :members: + :undoc-members: + :show-inheritance: + +simopt.models.paramesti module +------------------------------ + +.. automodule:: simopt.models.paramesti + :members: + :undoc-members: + :show-inheritance: + +simopt.models.rmitd module +-------------------------- + +.. automodule:: simopt.models.rmitd + :members: + :undoc-members: + :show-inheritance: + +simopt.models.san module +------------------------ + +.. automodule:: simopt.models.san + :members: + :undoc-members: + :show-inheritance: + +simopt.models.sscont module +--------------------------- + +.. automodule:: simopt.models.sscont + :members: + :undoc-members: + :show-inheritance: + +simopt.models.tableallocation module +------------------------------------ + +.. automodule:: simopt.models.tableallocation + :members: + :undoc-members: + :show-inheritance: + +Module contents +--------------- + +.. automodule:: simopt.models + :members: + :undoc-members: + :show-inheritance: diff --git a/docs/simopt.rst b/docs/source/simopt.rst similarity index 93% rename from docs/simopt.rst rename to docs/source/simopt.rst index 95e537949..b61d966ea 100644 --- a/docs/simopt.rst +++ b/docs/source/simopt.rst @@ -1,62 +1,62 @@ -simopt package -============== - -Subpackages ------------ - -.. toctree:: - :maxdepth: 4 - - simopt.models - simopt.solvers - -Submodules ----------- - -simopt.GUI module ------------------ - -.. automodule:: simopt.GUI - :members: - :undoc-members: - :show-inheritance: - -simopt.base module ------------------- - -.. automodule:: simopt.base - :members: - :undoc-members: - :show-inheritance: - -simopt.data\_farming\_base module ---------------------------------- - -.. automodule:: simopt.data_farming_base - :members: - :undoc-members: - :show-inheritance: - -simopt.directory module ------------------------ - -.. automodule:: simopt.directory - :members: - :undoc-members: - :show-inheritance: - -simopt.experiment\_base module ------------------------------- - -.. automodule:: simopt.experiment_base - :members: - :undoc-members: - :show-inheritance: - -Module contents ---------------- - -.. automodule:: simopt - :members: - :undoc-members: - :show-inheritance: +simopt package +============== + +Subpackages +----------- + +.. toctree:: + :maxdepth: 4 + + simopt.models + simopt.solvers + +Submodules +---------- + +simopt.GUI module +----------------- + +.. automodule:: simopt.GUI + :members: + :undoc-members: + :show-inheritance: + +simopt.base module +------------------ + +.. automodule:: simopt.base + :members: + :undoc-members: + :show-inheritance: + +simopt.data\_farming\_base module +--------------------------------- + +.. automodule:: simopt.data_farming_base + :members: + :undoc-members: + :show-inheritance: + +simopt.directory module +----------------------- + +.. automodule:: simopt.directory + :members: + :undoc-members: + :show-inheritance: + +simopt.experiment\_base module +------------------------------ + +.. automodule:: simopt.experiment_base + :members: + :undoc-members: + :show-inheritance: + +Module contents +--------------- + +.. automodule:: simopt + :members: + :undoc-members: + :show-inheritance: diff --git a/docs/simopt.solvers.rst b/docs/source/simopt.solvers.rst similarity index 94% rename from docs/simopt.solvers.rst rename to docs/source/simopt.solvers.rst index 9bd5a49e3..dec7b9e03 100644 --- a/docs/simopt.solvers.rst +++ b/docs/source/simopt.solvers.rst @@ -1,69 +1,69 @@ -simopt.solvers package -====================== - -Submodules ----------- - -simopt.solvers.adam module --------------------------- - -.. automodule:: simopt.solvers.adam - :members: - :undoc-members: - :show-inheritance: - -simopt.solvers.aloe module --------------------------- - -.. automodule:: simopt.solvers.aloe - :members: - :undoc-members: - :show-inheritance: - -simopt.solvers.astrodf module ------------------------------ - -.. automodule:: simopt.solvers.astrodf - :members: - :undoc-members: - :show-inheritance: - -simopt.solvers.neldmd module ----------------------------- - -.. automodule:: simopt.solvers.neldmd - :members: - :undoc-members: - :show-inheritance: - -simopt.solvers.randomsearch module ----------------------------------- - -.. automodule:: simopt.solvers.randomsearch - :members: - :undoc-members: - :show-inheritance: - -simopt.solvers.spsa module --------------------------- - -.. automodule:: simopt.solvers.spsa - :members: - :undoc-members: - :show-inheritance: - -simopt.solvers.strong module ----------------------------- - -.. automodule:: simopt.solvers.strong - :members: - :undoc-members: - :show-inheritance: - -Module contents ---------------- - -.. automodule:: simopt.solvers - :members: - :undoc-members: - :show-inheritance: +simopt.solvers package +====================== + +Submodules +---------- + +simopt.solvers.adam module +-------------------------- + +.. automodule:: simopt.solvers.adam + :members: + :undoc-members: + :show-inheritance: + +simopt.solvers.aloe module +-------------------------- + +.. automodule:: simopt.solvers.aloe + :members: + :undoc-members: + :show-inheritance: + +simopt.solvers.astrodf module +----------------------------- + +.. automodule:: simopt.solvers.astrodf + :members: + :undoc-members: + :show-inheritance: + +simopt.solvers.neldmd module +---------------------------- + +.. automodule:: simopt.solvers.neldmd + :members: + :undoc-members: + :show-inheritance: + +simopt.solvers.randomsearch module +---------------------------------- + +.. automodule:: simopt.solvers.randomsearch + :members: + :undoc-members: + :show-inheritance: + +simopt.solvers.spsa module +-------------------------- + +.. automodule:: simopt.solvers.spsa + :members: + :undoc-members: + :show-inheritance: + +simopt.solvers.strong module +---------------------------- + +.. automodule:: simopt.solvers.strong + :members: + :undoc-members: + :show-inheritance: + +Module contents +--------------- + +.. automodule:: simopt.solvers + :members: + :undoc-members: + :show-inheritance: diff --git a/docs/solvers.rst b/docs/source/solvers.rst similarity index 94% rename from docs/solvers.rst rename to docs/source/solvers.rst index c95a4d817..d3e03e7e2 100644 --- a/docs/solvers.rst +++ b/docs/source/solvers.rst @@ -1,45 +1,45 @@ -solvers package -=============== - -Submodules ----------- - -solvers.astrodf module ----------------------- - -.. automodule:: solvers.astrodf - :members: - :undoc-members: - :show-inheritance: - -solvers.neldmd module ---------------------- - -.. automodule:: solvers.neldmd - :members: - :undoc-members: - :show-inheritance: - -solvers.randomsearch module ---------------------------- - -.. automodule:: solvers.randomsearch - :members: - :undoc-members: - :show-inheritance: - -solvers.strong module ---------------------- - -.. automodule:: solvers.strong - :members: - :undoc-members: - :show-inheritance: - -Module contents ---------------- - -.. automodule:: solvers - :members: - :undoc-members: - :show-inheritance: +solvers package +=============== + +Submodules +---------- + +solvers.astrodf module +---------------------- + +.. automodule:: solvers.astrodf + :members: + :undoc-members: + :show-inheritance: + +solvers.neldmd module +--------------------- + +.. automodule:: solvers.neldmd + :members: + :undoc-members: + :show-inheritance: + +solvers.randomsearch module +--------------------------- + +.. automodule:: solvers.randomsearch + :members: + :undoc-members: + :show-inheritance: + +solvers.strong module +--------------------- + +.. automodule:: solvers.strong + :members: + :undoc-members: + :show-inheritance: + +Module contents +--------------- + +.. automodule:: solvers + :members: + :undoc-members: + :show-inheritance: diff --git a/docs/spsa.rst b/docs/source/spsa.rst similarity index 96% rename from docs/spsa.rst rename to docs/source/spsa.rst index 2497e7510..c214b6ad9 100644 --- a/docs/spsa.rst +++ b/docs/source/spsa.rst @@ -1,65 +1,65 @@ -Solver: Simultaneous Perturbation Stochastic Approximation (SPSA) -================================================================= - -Description: ------------- -SPSA is an iterative algorithm that approximates the gradient based on function evaluations taken at two points: one in a random direction and the other in the opposite direction. - -Modifications & Implementation: -------------------------------- -SPSA's main feature is the gradient approximation that requires only two objective function measurements per iteration. -The gradient approximtation calculation used in this solver is the weigthed average of the two objective function measurements, -with the weights reflecting the distances between the two neighbors and the incumbent solution. - -Scope: ------- -* objective_type: single - -* constraint_type: box - -* variable_type: continuous - -* gradient_observations: not available - -Solver Factors: ---------------- -* crn_across_solns: Use CRN across solutions? - - * Default: True - -* alpha: Non-negative coefficient in the SPSA gain sequecence ak. - - * Default: 0.602 - -* gamma: Non-negative coefficient in the SPSA gain sequecence ck. - - * Default: 0.101 - -* step: The initial desired magnitude of change in the theta elements. - - * Default: 0.1 - -* gavg: Averaged SP gradients used per iteration. - - * Default: 1 - -* n_reps: Number of replications takes at each solution. - - * Default: 30 - -* n_loss: Number of loss function evaluations used in this gain calculation. - - * Default: 2 - -* eval_pct: Percentage of the expected number of loss evaluations per run. - - * Default: 2 / 3 - -* iter_pct: Percentage of the maximum expected number of iterations. - - * Default: 0.1 - -References: -=========== -This solver is adapted from the article Spall, J. C. (1998). Implementation of simultaneous perturbation algorithm for stochastic optimization. IEEE Transactions on Aerospace and Electronic Systems 34(3):817-823. +Solver: Simultaneous Perturbation Stochastic Approximation (SPSA) +================================================================= + +Description: +------------ +SPSA is an iterative algorithm that approximates the gradient based on function evaluations taken at two points: one in a random direction and the other in the opposite direction. + +Modifications & Implementation: +------------------------------- +SPSA's main feature is the gradient approximation that requires only two objective function measurements per iteration. +The gradient approximtation calculation used in this solver is the weigthed average of the two objective function measurements, +with the weights reflecting the distances between the two neighbors and the incumbent solution. + +Scope: +------ +* objective_type: single + +* constraint_type: box + +* variable_type: continuous + +* gradient_observations: not available + +Solver Factors: +--------------- +* crn_across_solns: Use CRN across solutions? + + * Default: True + +* alpha: Non-negative coefficient in the SPSA gain sequecence ak. + + * Default: 0.602 + +* gamma: Non-negative coefficient in the SPSA gain sequecence ck. + + * Default: 0.101 + +* step: The initial desired magnitude of change in the theta elements. + + * Default: 0.1 + +* gavg: Averaged SP gradients used per iteration. + + * Default: 1 + +* n_reps: Number of replications takes at each solution. + + * Default: 30 + +* n_loss: Number of loss function evaluations used in this gain calculation. + + * Default: 2 + +* eval_pct: Percentage of the expected number of loss evaluations per run. + + * Default: 2 / 3 + +* iter_pct: Percentage of the maximum expected number of iterations. + + * Default: 0.1 + +References: +=========== +This solver is adapted from the article Spall, J. C. (1998). Implementation of simultaneous perturbation algorithm for stochastic optimization. IEEE Transactions on Aerospace and Electronic Systems 34(3):817-823. (https://ieeexplore.ieee.org/document/705889) \ No newline at end of file diff --git a/docs/sscont.rst b/docs/source/sscont.rst similarity index 98% rename from docs/sscont.rst rename to docs/source/sscont.rst index ad73b49e9..8e609f905 100644 --- a/docs/sscont.rst +++ b/docs/source/sscont.rst @@ -1,39 +1,39 @@ - -(s,S) Inventory System -====================== - -This example is adapted (almost verbatim) from the article Kleijnen, J.P.C. et al. Constrained Optimization in Simulation: A Novel Approach, Discussion Paper 2008-95, Tilburg University, Center for Economic Research. - -Consider a (s,S) inventory model with full backlogging. Demand during each period, :math:`D_t` is distributed -exponential with mean :math:`\mu`. At the end of each period, the inventory position :math:`(IP_t = \text{Stock on hand} - -\text{Backorders + Outstanding Orders})` is calculated and, if it is below :math:`s`, an order to get back up to :math:`S` is placed :math:`(O_t = \max(\mathbb{I}(IP_t < s)(S − IP_t), 0)`. Lead times have a Poisson distribution with mean :math:`\theta` days and all -replenishment orders are received at the beginning of the period. Note that, since orders are placed at the -end of the day, an order with lead time :math:`l` placed in period :math:`n` will arrive at the beginning of period :math:`n + l + 1`. - -A per unit holding cost :math:`h` is charged for inventory on-hand; furthermore, there is a fixed order cost :math:`f` -and a variable, per unit, cost :math:`c`. Our goal is to find :math:`s` and :math:`S` in order to minimize the :math:`\mathbb{E}[\text{Total cost per period}]` such that the stockout rate :math:`\delta`, the fraction of demand not supplied from stock on-hand, is at most -:math:`10\%`. To further clarify the order of events and the calculation of costs, a 5-day example in which :math:`s = 1000` -and :math:`S = 1500`, the initial inventory on hand is :math:`1000` and there are no outstanding orders is provided below. - -*Recommended Parameter Settings:* Take :math:`\mu = 100`, :math:`\theta = 6`, :math:`h = 1`, :math:`f = 36` and :math:`c = 2`. - -*Starting Solutions:* :math:`s = 1000`, :math:`S = 2000`. - -If multiple solutions are needed, use :math:`s ∼Uniform(700,1000)`, :math:`S ∼Uniform(1500,2000)`. - -*Measurement of Time:* Days simulated - -*Optimal Solution:* Unknown - -.. image:: sscont.png - :alt: The example table has failed to display - :width: 800 - - -.. examples of using math, first is for centered math on its own line, second is for inline - -.. .. math:: - - \frac{ \sum_{t=0}^{N}f(t,k) }{N} - + +(s,S) Inventory System +====================== + +This example is adapted (almost verbatim) from the article Kleijnen, J.P.C. et al. Constrained Optimization in Simulation: A Novel Approach, Discussion Paper 2008-95, Tilburg University, Center for Economic Research. + +Consider a (s,S) inventory model with full backlogging. Demand during each period, :math:`D_t` is distributed +exponential with mean :math:`\mu`. At the end of each period, the inventory position :math:`(IP_t = \text{Stock on hand} - +\text{Backorders + Outstanding Orders})` is calculated and, if it is below :math:`s`, an order to get back up to :math:`S` is placed :math:`(O_t = \max(\mathbb{I}(IP_t < s)(S − IP_t), 0)`. Lead times have a Poisson distribution with mean :math:`\theta` days and all +replenishment orders are received at the beginning of the period. Note that, since orders are placed at the +end of the day, an order with lead time :math:`l` placed in period :math:`n` will arrive at the beginning of period :math:`n + l + 1`. + +A per unit holding cost :math:`h` is charged for inventory on-hand; furthermore, there is a fixed order cost :math:`f` +and a variable, per unit, cost :math:`c`. Our goal is to find :math:`s` and :math:`S` in order to minimize the :math:`\mathbb{E}[\text{Total cost per period}]` such that the stockout rate :math:`\delta`, the fraction of demand not supplied from stock on-hand, is at most +:math:`10\%`. To further clarify the order of events and the calculation of costs, a 5-day example in which :math:`s = 1000` +and :math:`S = 1500`, the initial inventory on hand is :math:`1000` and there are no outstanding orders is provided below. + +*Recommended Parameter Settings:* Take :math:`\mu = 100`, :math:`\theta = 6`, :math:`h = 1`, :math:`f = 36` and :math:`c = 2`. + +*Starting Solutions:* :math:`s = 1000`, :math:`S = 2000`. + +If multiple solutions are needed, use :math:`s ∼Uniform(700,1000)`, :math:`S ∼Uniform(1500,2000)`. + +*Measurement of Time:* Days simulated + +*Optimal Solution:* Unknown + +.. image:: sscont.png + :alt: The example table has failed to display + :width: 800 + + +.. examples of using math, first is for centered math on its own line, second is for inline + +.. .. math:: + + \frac{ \sum_{t=0}^{N}f(t,k) }{N} + .. Since Pythagoras, we know that :math:`\frac{ \sum_{t=0}^{N}f(t,k) }{N}` \ No newline at end of file diff --git a/docs/strong.rst b/docs/source/strong.rst similarity index 96% rename from docs/strong.rst rename to docs/source/strong.rst index dfe31a0ed..ad95d3dd9 100644 --- a/docs/strong.rst +++ b/docs/source/strong.rst @@ -1,94 +1,94 @@ -Solver: Stochastic Trust-Region Response-Surface Method (STRONG) -================================================================ - -Description: ------------- -The solver estimates the shape of the underlying response distribution, -through function evaluations taken within a neighborhood of the incumbent solution. -STRONG has two stages in each iteration where a sub trust region is defined: -stage I optimizes a first-order polynomial, and stage II optimizes a second-order -polynomial. If stage II fails to generate a good solution, an inner loop is initiated -where value, gradient, and Hessian of the center point are further calculated. - - -Modifications & Implementation: -------------------------------- -Process within a stage: -We first find the Cauchy Point and the new solution in order to create a polynomial. -Then, the solver either shrinks trust region size, or moves the center point while the -trust region size stays constant, or moves the center point while the trust region enlarges. - -Helper functions: -There are 3 helper functions in addition to the main algorithm. - - * **cauchy_point** finds the Cauchy Point by using the gradient and Hessian matrix to find the steepest descent direction. - - * **check_cons** checks the feasibility of the Cauchy point and updates the point accordingly. - - * **finite_diff** uses finite difference to estimate gradients and BFGS to estimate the Hessian matrix. - -Scope: ------- -* objective_type: single - -* constraint_type: box - -* variable_type: continuous - - -Solver Factors: ---------------- -* crn_across_solns: Use CRN across solutions? - - * Default: True - -* n0: Initial sample size - - * Default: 10 - -* n_r: Number of replications taken at each solution - - * Default: 10 - -* sensitivity: shrinking scale for VarBds - - * Default: 10**(-7) - -* delta_threshold: maximum value of the radius - - * Default: 1.2 - -* delta_T: initial size of trust region - - * Default: 2 - -* eta_0: the constant of accepting - - * Default: 0.01 - -* eta_1: the constant of more confident accepting - - * Default: 0.3 - -* gamma_1: the constant of shrinking the trust regionthe new solution - - * Default: 0.9 - -* gamma_2: the constant of expanding the trust region - - * Default: 1.11 - -* lambda: multiplicative factor for n_r within finite difference - - * Default: 2 - -* lambda_2: magnifying factor for n_r in stage I and stage II - - * Default: 1.01 - -References: -=========== -This solver is adapted from the article Kuo-Hao Chang, L. Jeff Hong, Hong Wan, (2013). -Stochastic Trust-Region Response-Surface Method (STRONG) - A New Response-Surface Framework for Simulation Optimization. -*INFORMS Journal on Computing*, 25(2):230-243. -(https://doi.org/10.1287/ijoc.1120.0498) +Solver: Stochastic Trust-Region Response-Surface Method (STRONG) +================================================================ + +Description: +------------ +The solver estimates the shape of the underlying response distribution, +through function evaluations taken within a neighborhood of the incumbent solution. +STRONG has two stages in each iteration where a sub trust region is defined: +stage I optimizes a first-order polynomial, and stage II optimizes a second-order +polynomial. If stage II fails to generate a good solution, an inner loop is initiated +where value, gradient, and Hessian of the center point are further calculated. + + +Modifications & Implementation: +------------------------------- +Process within a stage: +We first find the Cauchy Point and the new solution in order to create a polynomial. +Then, the solver either shrinks trust region size, or moves the center point while the +trust region size stays constant, or moves the center point while the trust region enlarges. + +Helper functions: +There are 3 helper functions in addition to the main algorithm. + + * **cauchy_point** finds the Cauchy Point by using the gradient and Hessian matrix to find the steepest descent direction. + + * **check_cons** checks the feasibility of the Cauchy point and updates the point accordingly. + + * **finite_diff** uses finite difference to estimate gradients and BFGS to estimate the Hessian matrix. + +Scope: +------ +* objective_type: single + +* constraint_type: box + +* variable_type: continuous + + +Solver Factors: +--------------- +* crn_across_solns: Use CRN across solutions? + + * Default: True + +* n0: Initial sample size + + * Default: 10 + +* n_r: Number of replications taken at each solution + + * Default: 10 + +* sensitivity: shrinking scale for VarBds + + * Default: 10**(-7) + +* delta_threshold: maximum value of the radius + + * Default: 1.2 + +* delta_T: initial size of trust region + + * Default: 2 + +* eta_0: the constant of accepting + + * Default: 0.01 + +* eta_1: the constant of more confident accepting + + * Default: 0.3 + +* gamma_1: the constant of shrinking the trust regionthe new solution + + * Default: 0.9 + +* gamma_2: the constant of expanding the trust region + + * Default: 1.11 + +* lambda: multiplicative factor for n_r within finite difference + + * Default: 2 + +* lambda_2: magnifying factor for n_r in stage I and stage II + + * Default: 1.01 + +References: +=========== +This solver is adapted from the article Kuo-Hao Chang, L. Jeff Hong, Hong Wan, (2013). +Stochastic Trust-Region Response-Surface Method (STRONG) - A New Response-Surface Framework for Simulation Optimization. +*INFORMS Journal on Computing*, 25(2):230-243. +(https://doi.org/10.1287/ijoc.1120.0498) diff --git a/docs/tableallocation.rst b/docs/source/tableallocation.rst similarity index 96% rename from docs/tableallocation.rst rename to docs/source/tableallocation.rst index 99d477110..8050c933e 100644 --- a/docs/tableallocation.rst +++ b/docs/source/tableallocation.rst @@ -1,104 +1,104 @@ -Model: Restaurant Table Management (TABLEALLOCATION) -==================================================== - -Description: ------------- -Floor space in a restaurant is allocated to N different sizes of tables, with capacities -:math:`c = [c_1, c_2,..., c_N ], c_i \in Z_+^{n}`. A table of capacity :math:`c_i` can seat -:math:`c_i` customers or fewer. -The restaurant can seat a maximum of :math:`K` customers at a time, -regardless of table allocation, and is open for :math:`T` consecutive hours. -The decision variable is the vector :math:`x` representing -the number of tables allocated to each size. - -Customers arrive in groups of size :math:`j \in \{1, ..., max_i(c_i)\}` according to a homogeneous -Poisson process with rate :math:`\lambda_j`. A group of customers is seated at the smallest possible -available table. If there are no available tables large enough, the group of customers -leaves immediately. Service time per group is exponential and revenue per group is fixed. - -Sources of Randomness: ----------------------- -Groups of customers arrive according to a homogenrous Poisson process. Group size is randomly generated -with probability proportional to each group's average arrival rate. Service time per group is exponential. - -Model Factors: --------------- -* n_hour: Number of hours to simulate. - - * Default: 3 - -* capacity: Maximum total capacity. - - * Default: 80 - -* table_cap: Capacity of each type of table. - - * Default: [2, 4, 6, 8] - -* lambda: Average number of arrivals per hour. - - * Default: [3, 6, 3, 3, 2, 4/3, 6/5, 1] - -* service_time_means: Mean service time in minutes. - - * Default: [20, 25, 30, 35, 40, 45, 50, 60] - -* table_revenue: Revenue earned for each group size. - - * Default: [15, 30, 45, 60, 75, 90, 105, 120] - -* num_tables: Number of tables of each capacity. - - * Default: [10,5,4,2] - -Responses: ----------- -* total_revenue: Total revenue earned over the simulation period. - -* service_rate: Fraction of customer arrivals that are seated. - -References: -=========== -Original author of this problem is Bryan Chong (March 10, 2015). - - -Optimization Problem: Maximize Revenue (TABLEALLOCATION-1) -========================================================== - -Decision Variables: -------------------- -* num_tables - -Objectives: ------------ -Maximize the total expected revenue for a restaurant operation. - -Constraints: ------------- -Number of seats in the restaurant :math:`<= capacity`. - -Problem Factors: ----------------- -* budget: Max # of replications for a solver to take. - - * Default: 1000 - -Fixed Model Factors: --------------------- -N/A - -Starting Solution: ------------------- -* num_tables: [10, 5, 4, 2]. Corresponds to 10 tables of size 2, 5 tables of size 4, 4 tables of size 6, and 2 tables of size 8. - -Random Solutions: ------------------ -Distribute total capacity uniformly across table sizes. If the remaining capacity is smaller than the smallest table size, keep the last table allocation as a starting solution. - -Optimal Solution: ------------------ -Unknown. - -Optimal Objective Function Value: ---------------------------------- +Model: Restaurant Table Management (TABLEALLOCATION) +==================================================== + +Description: +------------ +Floor space in a restaurant is allocated to N different sizes of tables, with capacities +:math:`c = [c_1, c_2,..., c_N ], c_i \in Z_+^{n}`. A table of capacity :math:`c_i` can seat +:math:`c_i` customers or fewer. +The restaurant can seat a maximum of :math:`K` customers at a time, +regardless of table allocation, and is open for :math:`T` consecutive hours. +The decision variable is the vector :math:`x` representing +the number of tables allocated to each size. + +Customers arrive in groups of size :math:`j \in \{1, ..., max_i(c_i)\}` according to a homogeneous +Poisson process with rate :math:`\lambda_j`. A group of customers is seated at the smallest possible +available table. If there are no available tables large enough, the group of customers +leaves immediately. Service time per group is exponential and revenue per group is fixed. + +Sources of Randomness: +---------------------- +Groups of customers arrive according to a homogenrous Poisson process. Group size is randomly generated +with probability proportional to each group's average arrival rate. Service time per group is exponential. + +Model Factors: +-------------- +* n_hour: Number of hours to simulate. + + * Default: 3 + +* capacity: Maximum total capacity. + + * Default: 80 + +* table_cap: Capacity of each type of table. + + * Default: [2, 4, 6, 8] + +* lambda: Average number of arrivals per hour. + + * Default: [3, 6, 3, 3, 2, 4/3, 6/5, 1] + +* service_time_means: Mean service time in minutes. + + * Default: [20, 25, 30, 35, 40, 45, 50, 60] + +* table_revenue: Revenue earned for each group size. + + * Default: [15, 30, 45, 60, 75, 90, 105, 120] + +* num_tables: Number of tables of each capacity. + + * Default: [10,5,4,2] + +Responses: +---------- +* total_revenue: Total revenue earned over the simulation period. + +* service_rate: Fraction of customer arrivals that are seated. + +References: +=========== +Original author of this problem is Bryan Chong (March 10, 2015). + + +Optimization Problem: Maximize Revenue (TABLEALLOCATION-1) +========================================================== + +Decision Variables: +------------------- +* num_tables + +Objectives: +----------- +Maximize the total expected revenue for a restaurant operation. + +Constraints: +------------ +Number of seats in the restaurant :math:`<= capacity`. + +Problem Factors: +---------------- +* budget: Max # of replications for a solver to take. + + * Default: 1000 + +Fixed Model Factors: +-------------------- +N/A + +Starting Solution: +------------------ +* num_tables: [10, 5, 4, 2]. Corresponds to 10 tables of size 2, 5 tables of size 4, 4 tables of size 6, and 2 tables of size 8. + +Random Solutions: +----------------- +Distribute total capacity uniformly across table sizes. If the remaining capacity is smaller than the smallest table size, keep the last table allocation as a starting solution. + +Optimal Solution: +----------------- +Unknown. + +Optimal Objective Function Value: +--------------------------------- Unknown. \ No newline at end of file diff --git a/docs/test.rst b/docs/source/test.rst similarity index 93% rename from docs/test.rst rename to docs/source/test.rst index f539c2381..faf5dc4d8 100644 --- a/docs/test.rst +++ b/docs/source/test.rst @@ -1,29 +1,29 @@ -test package -============ - -Submodules ----------- - -test.run\_template module -------------------------- - -.. automodule:: test.run_template - :members: - :undoc-members: - :show-inheritance: - -test.test\_runner module ------------------------- - -.. automodule:: test.test_runner - :members: - :undoc-members: - :show-inheritance: - -Module contents ---------------- - -.. automodule:: test - :members: - :undoc-members: - :show-inheritance: +test package +============ + +Submodules +---------- + +test.run\_template module +------------------------- + +.. automodule:: test.run_template + :members: + :undoc-members: + :show-inheritance: + +test.test\_runner module +------------------------ + +.. automodule:: test.test_runner + :members: + :undoc-members: + :show-inheritance: + +Module contents +--------------- + +.. automodule:: test + :members: + :undoc-members: + :show-inheritance: From c3f4b224316f483a4751f4e236450485d0281e37 Mon Sep 17 00:00:00 2001 From: William Grochocinski Date: Wed, 5 Mar 2025 15:37:58 -0500 Subject: [PATCH 2/3] add github workflow to automatically build documentation --- .github/workflows/sphinx.yml | 33 +++++++++++++++++++++++++++++++++ 1 file changed, 33 insertions(+) create mode 100644 .github/workflows/sphinx.yml diff --git a/.github/workflows/sphinx.yml b/.github/workflows/sphinx.yml new file mode 100644 index 000000000..83e9282c2 --- /dev/null +++ b/.github/workflows/sphinx.yml @@ -0,0 +1,33 @@ +name: Sphinx Docs Build + +on: + push: + branches: [ "master", "development" ] + +jobs: + build: + runs-on: ubuntu-latest + steps: + - name: Checkout repository + uses: actions/checkout@v3 + with: + fetch-depth: 0 + ref: ${{ github.ref }} + + - name: Set up Python + uses: actions/setup-python@v4 + with: + python-version: '3.9' + + - name: Install dependencies + run: pip install -r docs/requirements.txt + + - name: Build documentation + run: sphinx-build -b html docs/source docs/_build/html + + - name: Commit and push changes + run: | + git config --global user.name "github-actions[bot]" + git config --global user.email "github-actions[bot]@users.noreply.github.com" + git add docs/_build/html + git diff --quiet && echo "No changes to commit" || (git commit -m "Automated documentation update" && git push origin HEAD:${GITHUB_REF#refs/heads/}) From e52259e6e21ba1262cf6504168696227167e08b6 Mon Sep 17 00:00:00 2001 From: William Grochocinski Date: Wed, 5 Mar 2025 15:40:42 -0500 Subject: [PATCH 3/3] fixed formatting --- docs/source/conf.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/source/conf.py b/docs/source/conf.py index 2c3e6641b..629b2a0eb 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -89,7 +89,7 @@ # relative to this directory. They are copied after the builtin static files, # so a file named "default.css" will overwrite the builtin "default.css". -html_static_path = ['_static'] +html_static_path = ["_static"] main(["-o", os.path.abspath("."), os.path.abspath(".."), "-f"])