diff --git a/.readthedocs.yaml b/.readthedocs.yaml index af680974..8d20b3c1 100644 --- a/.readthedocs.yaml +++ b/.readthedocs.yaml @@ -6,7 +6,8 @@ sphinx: build: os: ubuntu-lts-latest tools: - python: miniconda-latest - -conda: - environment: docs/environment.yml \ No newline at end of file + python: "3.13" + jobs: + pre_install: + - python -m pip install --upgrade pip + - python -m pip install .[docs] \ No newline at end of file diff --git a/README.md b/README.md index a005931a..1d3285f6 100644 --- a/README.md +++ b/README.md @@ -1,4 +1,4 @@ -![SimOpt Logo](https://raw.githubusercontent.com/simopt-admin/simopt/master/.github/resources/logo_full_magnifying_glass.png) +![SimOpt Logo](https://raw.githubusercontent.com/simopt-admin/simopt/master/.github/resources/logo_full_arrows.png) ## About the Project SimOpt is a testbed of simulation-optimization problems and solvers. Its purpose is to encourage the 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. @@ -15,7 +15,7 @@ Several papers have discussed the development of SimOpt and experiments run on t * [Pasupathy and Henderson (2011)](https://www.informs-sim.org/wsc11papers/363.pdf) describes an earlier interface for MATLAB implementations of problems and solvers. * [Pasupathy and Henderson (2006)](https://www.informs-sim.org/wsc06papers/028.pdf) explains the original motivation for the testbed. -## Code +## Languages & Branches ### Python - The [`master branch`](https://github.com/simopt-admin/simopt/tree/master) contains the source code for the latest stable release of the testbed - The [`development branch`](https://github.com/simopt-admin/simopt/tree/development) contains the latest code for the testbed, but may contain more bugs than the master branch @@ -29,19 +29,18 @@ Full documentation for the source code can be found on our **[readthedocs page]( [![Documentation Status](https://readthedocs.org/projects/simopt/badge/?version=latest)](https://simopt.readthedocs.io/en/latest/?badge=latest) -## Getting Started +## Getting Started with SimOpt's Source Code ### Requirements -- [Miniconda or Anaconda](https://www.anaconda.com/download) - - If you already have a compatible IDE (such as VS Code), we've found that Miniconda will work fine at 1/10 of the size of Anaconda. Otherwise, you may need the Spyder IDE that comes with the full Anaconda distribution. - - It is ***highly recommended*** to check the box during installation to add Python/Miniconda/Anaconda to your system PATH. +- [Python >=3.11, <3.14](https://www.python.org/downloads/) - If you know you have Python installed but are getting a `Command not found` error when trying to use Python commands, then you may need to [add Python to your PATH](https://realpython.com/add-python-to-path/). -- [VS Code](https://code.visualstudio.com/download) (optional) - - This is a lightweight IDE that is compatible with Miniconda. +- A Python-compatible IDE + - We recommend using [VS Code](https://code.visualstudio.com/download), a very popular & lightweight IDE. - [Git](https://git-scm.com/downloads) (optional) - - If you don't have Git installed, you can download the code as a zip file instead + - Git is required if you wish to contribute back to the SimOpt project. If you simply want to run the SimOpt package, you can download the code as a zip file instead. ### Downloading Source Code -There are two ways to download a copy of the source code onto your machine: +There are two main ways to download a copy of the source code onto your machine: + 1. Download the code in a zip file by clicking the green `<> Code` button above repo contents and clicking the `Download ZIP` option, then unzip the code to a folder on your computer. This does not require `git` to be installed but makes downloading updates to the repository more challenging. ![image](https://github.com/user-attachments/assets/3c45804c-f8b0-48ed-b32c-a443550c6ef5) @@ -49,43 +48,40 @@ There are two ways to download a copy of the source code onto your machine: If you do not need the source code for SimOpt, you may install the library as a Python package instead. See the [Package](#package) and [Basic Example](#basic-example) sections for more details about this option. -The `notebooks` folder includes several useful Jupyter notebooks and scripts that are easy to customize. You can either run the scripts as standalone programs or open the notebooks in JupyterLab or VS Code. A description of the contents is provided below: - -| File | Description | -| ---------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -| `demo_model.py` | Run multiple replications of a simulation model and report its responses | -| `demo_problem.py` | Run multiple replications of a given solution for an SO problem and report its objective function values and left-hand sides of stochastic constraints | -| `demo_problem_solver.py` | Run multiple macroreplications of a solver on a problem, save the outputs to a `.pickle` file in the `experiments/outputs` folder, and save plots of the results to `.png` files in the `experiments/plots` folder | -| `demo_problems_solvers.py` | Run multiple macroreplications of groups of problem-solver pairs and save the outputs and plots | -| `demo_data_farming_model.py` | Create a design over model factors, run multiple replications at each design point, and save the results to a comma separated value (`.csv`) file in the `data_farming_experiments` folder | -| `demo_san-sscont-ironorecont_experiment` | Run multiple solvers on multiple versions of (s, S) inventory, iron ore, and stochastic activiy network problems and produce plots | - ### Environment Setup -After downloading the source code, you will need to configure the conda environment to run the code. This can be done by running the following command in the terminal: +Navigate to the toplevel folder of the `simopt` repository and run the following command to set up a virtual environment: -#### Windows (Command Prompt) -```cmd -setup_simopt.bat +```bash +python -m venv .venv --prompt simopt ``` -#### Windows (PowerShell) -```powershell -cmd /c setup_simopt.bat -``` +Then, activate the virtual environment with the following command: -#### MacOS/Linux ```bash -chmod +x setup_simopt.sh && ./setup_simopt.sh +.venv\Scripts\activate ``` -This script will create a new conda environment called `simopt` and install all necessary packages. To activate the environment, run the following command in the terminal: +Now all you need to do is install the required packages from the `pyproject.toml` file with the following command: ```bash -conda activate simopt +python -m pip install .[notebooks] ``` -If you wish to update the environment with the latest compatible packages, you can simply rerun the setup script. +Now that the environment is set up, you can run the example notebooks below or follow the instructions below to launch the GUI. + +### Example Notebooks + +The `notebooks` folder includes several useful Jupyter notebooks and scripts that are easy to customize. You can either run the scripts as standalone programs or open the notebooks in JupyterLab or VS Code. A description of the contents is provided below: + +| File | Description | +| ---------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| `demo_model.py` | Run multiple replications of a simulation model and report its responses | +| `demo_problem.py` | Run multiple replications of a given solution for an SO problem and report its objective function values and left-hand sides of stochastic constraints | +| `demo_problem_solver.py` | Run multiple macroreplications of a solver on a problem, save the outputs to a `.pickle` file in the `experiments/outputs` folder, and save plots of the results to `.png` files in the `experiments/plots` folder | +| `demo_problems_solvers.py` | Run multiple macroreplications of groups of problem-solver pairs and save the outputs and plots | +| `demo_data_farming_model.py` | Create a design over model factors, run multiple replications at each design point, and save the results to a comma separated value (`.csv`) file in the `data_farming_experiments` folder | +| `demo_san-sscont-ironorecont_experiment` | Run multiple solvers on multiple versions of (s, S) inventory, iron ore, and stochastic activiy network problems and produce plots | ## Graphical User Interface (GUI) - User Guide @@ -177,14 +173,16 @@ The type of plots that are currently available in the GUI are: Mean Progress Cur 7. To return to the main page, click the red "x" in the top-left corner of the window. ## Package +> ℹ️ The `simoptlib` package does not contain the example notebooks or testing suite. If you wish to use either of those features, please download the source code instead. + The `simoptlib` package is available to download through the Python Packaging Index (PyPI) and can be installed from the terminal with the following command: -``` +```bash python -m pip install simoptlib ``` ## Basic Example After installing `simoptlib`, the package's main modules can be imported from the Python console (or in code): -``` +```python import simopt from simopt import models, solvers, experiment_base ``` diff --git a/docs/environment.yml b/docs/environment.yml deleted file mode 100644 index 90634990..00000000 --- a/docs/environment.yml +++ /dev/null @@ -1,22 +0,0 @@ -name: simopt-docs -channels: - - conda-forge -dependencies: - # Base Python - - python=3.12 - # Sphinx and its dependencies - - sphinx - - sphinx_rtd_theme - # SimOpt dependencies - - numpy - - scipy - - jupyter - - matplotlib - - pandas - - seaborn - - pillow - - pip - - ruff - - pip: - - mrg32k3a - - sphinx-autoapi diff --git a/environment.yml b/environment.yml deleted file mode 100644 index 11fa9d8d..00000000 --- a/environment.yml +++ /dev/null @@ -1,21 +0,0 @@ -name: simopt -channels: - - conda-forge -dependencies: - - python>=3.11,<3.14 - - numpy>=2.3.4 - - scipy>=1.16.3 - - jupyter - - matplotlib>=3.10.7 - - pandas>=2.3.3 - - seaborn>=0.13.2 - - pillow>=12.0.0 - - pip - - ruff>=0.14.2 - - joblib>=1.5.2 - - boltons>=25.0.0 - - cvxpy>=1.7.3 - - pydantic>=2.12.3 - - pip: - - mrg32k3a>=2.0 - - -e . diff --git a/setup_simopt.bat b/setup_simopt.bat deleted file mode 100644 index a20247c7..00000000 --- a/setup_simopt.bat +++ /dev/null @@ -1,28 +0,0 @@ -@echo off -set ENV_NAME=simopt -set YML_FILE=environment.yml - -echo Checking for Conda installation... -where conda >nul 2>nul -if %errorlevel% neq 0 ( - echo Conda not found! Please install Miniconda or Anaconda first. - exit /b 1 -) - -:: Ensure Conda is initialized -call "%USERPROFILE%\miniconda3\Scripts\activate.bat" - -:: Check if environment already exists -conda env list | findstr /C:"%ENV_NAME%" >nul -if %errorlevel% == 0 ( - echo Environment "%ENV_NAME%" exists. Updating... - call conda env update --name "%ENV_NAME%" --file "%YML_FILE%" --prune -) else ( - echo Creating new environment "%ENV_NAME%"... - call conda env create -f "%YML_FILE%" -) - -:: Activate environment -call conda activate %ENV_NAME% - -echo Setup complete! Run: conda activate %ENV_NAME% diff --git a/setup_simopt.sh b/setup_simopt.sh deleted file mode 100755 index 9f3b34e9..00000000 --- a/setup_simopt.sh +++ /dev/null @@ -1,28 +0,0 @@ -#!/bin/bash - -ENV_NAME="simopt" -YML_FILE="environment.yml" - -echo "Checking for Conda installation..." -if ! command -v conda &> /dev/null; then - echo "Conda not found! Please install Miniconda or Anaconda first." - exit 1 -fi - -# Ensure Conda is initialized -source "$(conda info --base)/etc/profile.d/conda.sh" - -# Check if environment exists -if conda env list | grep -q "$ENV_NAME"; then - echo "Environment '$ENV_NAME' exists. Updating..." - conda env update --name "$ENV_NAME" --file "$YML_FILE" --prune -else - echo "Creating new environment '$ENV_NAME'..." - conda env create -f "$YML_FILE" -fi - -# Activate the Conda environment -echo "Activating environment..." -source activate "$ENV_NAME" - -echo "Setup complete! Run: conda activate $ENV_NAME"