fcvopt 0.4.0__tar.gz

fcvopt-0.4.0/.claude/settings.local.json

@@ -0,0 +1,20 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(source:*)",
+      "Bash(python3:*)",
+      "Bash(bash:*)",
+      "Bash(tree:*)",
+      "Bash(pip install:*)",
+      "Bash(python -m build:*)",
+      "Bash(twine check:*)",
+      "WebSearch",
+      "WebFetch(domain:pypi.org)",
+      "Bash(python -m unittest:*)",
+      "Bash(git rm:*)",
+      "Bash(find:*)"
+    ],
+    "deny": [],
+    "ask": []
+  }
+}

fcvopt-0.4.0/.dockerignore

@@ -0,0 +1,6 @@
+# Exclude directory
+notebooks/
+examples/
+.vscode/
+experiments/
+tests/

fcvopt-0.4.0/.github/workflows/docs.yml

@@ -0,0 +1,77 @@
+name: Build and Deploy Documentation
+
+on:
+  push:
+    branches: [ master, main ]
+    paths:
+      - 'docs/**'
+      - '.github/workflows/docs.yml'
+  pull_request:
+    branches: [ master, main ]
+    paths:
+      - 'docs/source/**'
+      - '.github/workflows/docs.yml'
+
+# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+# Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued.
+# However, do NOT cancel in-progress runs as we want to allow these production deployments to complete.
+concurrency:
+  group: "pages"
+  cancel-in-progress: false
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+
+    steps:
+    - name: Checkout
+      uses: actions/checkout@v4
+
+    - name: Set up Python
+      uses: actions/setup-python@v4
+      with:
+        python-version: '3.10'
+        cache: 'pip'  # Cache pip dependencies
+
+    - name: Install Pandoc
+      run: |
+        sudo apt-get update
+        sudo apt-get install -y pandoc
+
+    - name: Install dependencies
+      run: |
+        python -m pip install --upgrade pip
+        pip install -e .[docs,experiments]
+
+    - name: Build documentation
+      run: |
+        cd docs
+        make html
+
+    - name: Setup Pages
+      uses: actions/configure-pages@v4
+      if: github.ref == 'refs/heads/master' || github.ref == 'refs/heads/main'
+
+    - name: Upload artifact
+      uses: actions/upload-pages-artifact@v3
+      if: github.ref == 'refs/heads/master' || github.ref == 'refs/heads/main'
+      with:
+        path: './docs/build/html'
+
+  deploy:
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-latest
+    needs: build
+    if: github.ref == 'refs/heads/master' || github.ref == 'refs/heads/main'
+
+    steps:
+    - name: Deploy to GitHub Pages
+      id: deployment
+      uses: actions/deploy-pages@v4

fcvopt-0.4.0/.gitignore

@@ -0,0 +1,58 @@
+# Python compiled files
+*.pyc
+*.pyo
+*.pyd
+__pycache__/
+*.so
+*.dylib
+*.dll
+
+# Distribution / packaging
+build/
+dist/
+*.egg-info/
+.eggs/
+*.egg
+
+# Virtual environments
+fcvopt_test/
+venv/
+env/
+ENV/
+
+# IDEs
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+
+# OS files
+.DS_Store
+.DS_Store?
+._*
+.Spotlight-V100
+.Trashes
+Thumbs.db
+
+# Project specific
+test.py
+*.pkl
+*.pt
+*.pth
+*.csv
+*/hp_opt_runs/*
+docs/build/*
+examples/**runs/*
+
+# Quest/Slurm files
+*.e*
+*.o*
+
+# MLflow
+mlruns/
+mlartifacts/
+
+# Jupyter
+.ipynb_checkpoints/
+*.ipynb_checkpoints/

fcvopt-0.4.0/CLAUDE.md

@@ -0,0 +1,186 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+FCVOpt is a Python package (v0.4.0) for **Fractional Cross-Validation** in hyperparameter optimization. It implements efficient hyperparameter tuning by evaluating only a fraction of cross-validation folds using hierarchical Gaussian processes (HGP).
+
+**Key Innovation**: Instead of evaluating all K folds for every hyperparameter configuration, FCVOpt uses a hierarchical GP model to exploit fold-wise correlations, enabling optimization with only 1-2 folds evaluated per configuration—drastically reducing computation.
+
+## Installation & Setup
+
+### Virtual Environment Setup
+```bash
+chmod +x venv_setup.sh
+./venv_setup.sh
+source fcvopt_test/bin/activate
+```
+
+### Development Installation
+```bash
+pip install -e .                  # Core package
+pip install -e .[experiments]     # + experiment dependencies
+pip install -e .[docs]            # + documentation dependencies
+```
+
+### Docker Setup
+```bash
+docker build -t fcvopt_test .
+docker run -v $(pwd)/experiments:/app/experiments -it fcvopt_test
+```
+
+## Running Tests
+
+Tests use Python's `unittest` framework:
+
+```bash
+python -m unittest discover tests/              # All tests
+python -m unittest tests/test_fcvopt.py         # FCVOpt tests
+python -m unittest tests/test_bayes_opt.py      # BayesOpt tests
+python -m unittest tests.test_fcvopt.TestFCVOpt.test_initialization  # Single test
+```
+
+## Building Documentation
+
+```bash
+cd docs/
+make html    # Build HTML documentation
+make clean   # Clean build artifacts
+```
+
+Documentation: https://syerramilli.github.io/fcvopt/
+
+## Architecture Overview
+
+### Core Modules
+
+1. **`fcvopt/crossvalidation/`** - Cross-validation objective functions
+   - `cvobjective.py`: Base `CVObjective` abstract class
+   - `sklearn_cvobj.py`: `SklearnCVObj` wrapper for scikit-learn estimators, `XGBoostCVObjEarlyStopping` for XGBoost with early stopping
+   - `mlp_cvobj.py`: `MLPCVObj` for neural networks via Skorch
+   - `resnet_cvobj.py`: `ResNetCVObj` for TabResNet on tabular data
+   - `optuna_obj.py`: Integration with Optuna optimizer
+
+2. **`fcvopt/optimizers/`** - Bayesian optimization algorithms
+   - `bayes_opt.py`: `BayesOpt` class - standard BO with full K-fold CV
+   - `fcvopt.py`: `FCVOpt` class - fractional CV optimizer (main algorithm)
+   - `active_learning.py`: `ActiveLearning` class using posterior variance reduction
+   - `cvrandopt.py`: `CVRandOpt` random search baseline
+   - `mtbo_cv.py`: `MTBO_CV` multi-task BO variant
+   - `optimize_acq.py`: Acquisition function optimization utilities
+
+3. **`fcvopt/models/`** - Gaussian Process models
+   - `gpregression.py`: `GPR` - base GP regression model
+   - `hmgp.py`: `HGP` - Hierarchical GP for modeling fold-wise correlations
+   - `multitaskgp.py`: Multi-task GP for multiple outputs
+   - `warp.py`: Input warping transformations
+   - `priors.py`: Custom GP priors (e.g., `BetaPrior`)
+
+4. **`fcvopt/kernels/`** - Custom GP kernels
+   - `hamming_kernel.py`: `HammingKernel` for categorical fold indices
+   - `constant_kernel.py`: Constant kernel
+   - `matern.py`: Matérn kernel implementations
+   - `multitaskkernel.py`: Multi-task covariance functions
+
+5. **`fcvopt/configspace.py`** - Extended `ConfigurationSpace` wrapper
+   - `latinhypercube_sample()` for initial design sampling
+   - Conversion between Configuration objects and numeric arrays
+
+6. **`fcvopt/fit/mll_scipy.py`** - GP hyperparameter optimization via scipy L-BFGS-B
+
+7. **`fcvopt/util/samplers.py`** - Sampling utilities (Latin Hypercube, stratified)
+
+### Key Design Patterns
+
+**CVObjective Interface**: All CV objectives inherit from `CVObjective` and must implement:
+- `construct_model(params)`: Return unfitted model instance
+- `fit_and_test(params, train_index, test_index)`: Train and evaluate on one fold
+
+**Optimizer Hierarchy**: `FCVOpt` extends `BayesOpt`, overriding:
+- `_initialize()`: Assigns folds to initial random configurations
+- `_acquisition()`: Adds fold selection after candidate selection
+- `_construct_model()`: Uses `HGP` instead of standard GP
+- `_select_fold_indices()`: Chooses folds via variance reduction or random sampling
+
+**MLflow Integration**: Both `BayesOpt` and `FCVOpt` automatically track:
+- Hyperparameter configurations and losses
+- Model checkpoints (GP state)
+- Iteration snapshots with acquisition values
+
+### Data Flow in FCVOpt
+
+1. **Initialization**: Sample `n_init` random configs, assign folds (random/stratified), evaluate
+2. **Model Fitting**: Fit hierarchical GP on `(x, fold_idx) → y` observations
+3. **Acquisition**: Optimize acquisition function to select next configuration
+4. **Fold Selection**: Choose fold via variance reduction or random
+5. **Evaluation**: Evaluate objective on selected (config, fold) pair
+6. **Repeat**: Update GP, select next candidate
+
+## Example Notebooks
+
+Located in `examples/`:
+- `01_Introduction_to_FCVOpt.ipynb` - Basic usage and concepts
+- `02_Tuning_Lightgbm_Sklearn_API.ipynb` - LightGBM hyperparameter tuning
+- `03_Extending_CVobjective.ipynb` - Creating custom CV objectives
+- `04_Tuning_TabularResNet.ipynb` - TabResNet neural network tuning
+
+## Experiments
+
+Experiments for reproducing paper results are in `experiments/`:
+- `rf_high_dim/`: Random forest on high-dimensional data
+- `xgb_class/`: XGBoost classification
+- `boosted_reg/`: Gradient boosted regression
+- `mlp/`: Multi-layer perceptron via PyTorch
+- `tab_resnet/`: Tabular ResNet
+
+Utility scripts:
+- `generate_figures.py`: Create paper figures
+- `reproduce_rf.sh`: Bash script to run RF experiments
+
+## Dependencies
+
+**Core**: PyTorch (2.2.0), GPyTorch (1.9-1.10), BoTorch (>=0.8, <0.9), ConfigSpace (1.2.1), MLflow (>=3.0), scikit-learn, XGBoost, Skorch (0.13-0.15)
+
+**Note on SMAC**: Experiments using SMAC require `pyrfr`, which needs a C++ compiler and `swig`. This is optional.
+
+## Common Gotchas
+
+- **Categorical hyperparameters**: `latinhypercube_sample()` only supports binary-valued categoricals. Use `ConfigSpace.sample_configuration()` for general categoricals.
+
+- **MLflow tracking**: Optimizers auto-initialize MLflow. To use custom tracking URI, set before creating optimizer or pass `tracking_uri` parameter.
+
+- **Fold indices**: In `FCVOpt`, fold indices include repeats: with `n_folds=5` and `n_repeats=2`, valid fold indices are 0-9.
+
+- **EI acquisition**: Not supported for `FCVOpt` - use `'LCB'` or `'KG'` instead.
+
+- **LightGBM compatibility**: A fix has been applied in `fcvopt/fit/mll_scipy.py` to handle LightGBM's C++ objects. When `n_jobs=1` (default), only a single restart is used. When `n_jobs>1`, `ThreadPoolExecutor` is used instead of `joblib.Parallel` to avoid pickling issues. If you experience segfaults, clear `__pycache__` and reinstall: `pip install -e .`
+
+## Quick Usage Example
+
+```python
+from fcvopt.optimizers import FCVOpt
+from fcvopt.crossvalidation import SklearnCVObj
+from fcvopt.configspace import ConfigurationSpace
+from ConfigSpace import Float
+from sklearn.ensemble import RandomForestClassifier
+from sklearn.metrics import log_loss
+
+# Define hyperparameter space
+config = ConfigurationSpace(seed=42)
+config.add(Float('max_features', bounds=(0.1, 1.0)))
+config.add(Float('min_samples_leaf', bounds=(0.01, 0.1)))
+
+# Create CV objective
+cv_obj = SklearnCVObj(
+    estimator=RandomForestClassifier(n_estimators=100),
+    X=X_train, y=y_train,
+    task='classification',
+    loss_metric=log_loss,
+    n_splits=5
+)
+
+# Run fractional CV optimization
+optimizer = FCVOpt(obj=cv_obj, config=config, n_folds=5)
+best_config = optimizer.run(n_iter=20, n_init=5)
+```

fcvopt-0.4.0/Dockerfile

@@ -0,0 +1,24 @@
+FROM python:3.10
+
+# Set the working directory in the container
+WORKDIR /app
+
+# Copy the current directory contents into the container at /app
+# Note: The .dockerignore file is used to exclude certain files and directories 
+# from being copied. This includes the experiments directory which is not needed
+# for installing the library. It is recommnded to mount the experiments directory
+# as a volume when running the container.
+COPY . /app
+
+# Upgrade pip
+RUN pip install --upgrade pip
+
+# Install the CPU only version of PyTorch (the index-url must be specified for Linux distributions)
+RUN pip install torch==2.2.0 --index-url https://download.pytorch.org/whl/cpu
+
+# Install the fcvopt library along with required dependencies
+# and the extra dependencies for the experiments
+RUN pip install .[experiments]
+
+# Set the default command to run when the container starts
+ENTRYPOINT ["/bin/bash"]

fcvopt-0.4.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Suraj Yerramilli
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

fcvopt-0.4.0/PKG-INFO

@@ -0,0 +1,150 @@
+Metadata-Version: 2.4
+Name: fcvopt
+Version: 0.4.0
+Summary: Fractional K-fold cross-validation for hyperparameter optimization
+Project-URL: Homepage, https://github.com/syerramilli/fcvopt
+Project-URL: Documentation, https://syerramilli.github.io/fcvopt/
+Project-URL: Repository, https://github.com/syerramilli/fcvopt.git
+Project-URL: Issues, https://github.com/syerramilli/fcvopt/issues
+Author: Daniel W. Apley
+Author-email: Suraj Yerramilli <surajyerramilli@gmail.com>
+Maintainer-email: Suraj Yerramilli <surajyerramilli@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: automl,bayesian-optimization,cross-validation,gaussian-processes,hyperparameter-optimization,machine-learning
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Scientific/Engineering :: Information Analysis
+Requires-Python: >=3.10
+Requires-Dist: botorch>=0.12
+Requires-Dist: configspace<2.0,>=1.0
+Requires-Dist: gpytorch>=1.14
+Requires-Dist: joblib>=1.3
+Requires-Dist: mlflow>=2.10
+Requires-Dist: numpy>=2.0
+Requires-Dist: pandas>=2.2.2
+Requires-Dist: scikit-learn>=1.4.2
+Requires-Dist: scipy>=1.12
+Requires-Dist: skorch>=0.15
+Requires-Dist: torch>=2.3.1
+Requires-Dist: xgboost<3,>=2.0.0
+Provides-Extra: dev
+Requires-Dist: black; extra == 'dev'
+Requires-Dist: flake8; extra == 'dev'
+Requires-Dist: isort; extra == 'dev'
+Requires-Dist: pytest-cov; extra == 'dev'
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Provides-Extra: docs
+Requires-Dist: ipykernel; extra == 'docs'
+Requires-Dist: nbsphinx; extra == 'docs'
+Requires-Dist: sphinx-autodoc-typehints; extra == 'docs'
+Requires-Dist: sphinx-rtd-theme; extra == 'docs'
+Requires-Dist: sphinx>=4.0; extra == 'docs'
+Requires-Dist: sphinxcontrib-napoleon; extra == 'docs'
+Provides-Extra: experiments
+Requires-Dist: lightgbm>=4.0; extra == 'experiments'
+Requires-Dist: matplotlib>=3.7.0; extra == 'experiments'
+Requires-Dist: optuna<4.0.0,>=3.6.0; extra == 'experiments'
+Requires-Dist: seaborn>=0.12.2; extra == 'experiments'
+Requires-Dist: smac<3.0,>=2.0; extra == 'experiments'
+Description-Content-Type: text/markdown
+
+# fcvopt: Fractional cross-validation for hyperparameter optimization
+
+FCVOpt is a Python package for "Fractional Cross-Validation"in hyperparameter optimization. It implements efficient hyperparameter tuning by evaluating only a fraction of cross-validation folds using hierarchical Gaussian processes.
+
+The documentation is available at [https://syerramilli.github.io/fcvopt/](https://syerramilli.github.io/fcvopt/).
+
+🚀 **Key Features**:
+
+* **Efficient Optimization**: Evaluate hyperparameters using only a subset of CV folds
+* **Hierarchical Gaussian Processes**: Model fold-wise correlations for better predictions
+* **MLflow Integration**: Automatic experiment tracking and model versioning
+* **Framework Support**: Scikit-learn, XGBoost, PyTorch (via Skorch), and more
+
+## Installation
+
+### From Source
+
+```{bash}
+git clone https://github.com/syerramilli/fcvopt.git
+cd fcvopt
+pip install .
+```
+
+**With optional dependencies**:
+
+```{bash}
+pip install .[experiments]  # For reproducing the results from the paper
+pip install .[docs]         # For building documentation
+```
+
+## Citing
+If you use this code in your research, please cite the following paper:
+
+```
+@article{yerramilli2025fractional,
+    author = {Suraj Yerramilli and Daniel W. Apley},
+    title = {Fractional Cross-Validation for Optimizing Hyperparameters of Supervised Learning Algorithms},
+    journal = {Technometrics},
+    year = {2025},
+    doi = {10.1080/00401706.2025.2515926},
+}
+```
+
+## Reproducting the experiment results from the paper
+
+The experiments are all contained in the `experiments` folder. Each subdirectory within this folder contains scripts files to run each case study in the paper. Refer to the README file within each of the subdirectories for instructions to run the files.
+
+For reproducibility, we provide two options for setting up the environment to run the experiments: a virtual environment using `venv` and a Docker container.
+
+### Setting up a virtual environment
+
+The bash script file `venv_setup.sh` can be used to create a virtual environment and install the required packages. Ensure you have Python >= 3.8 and <=3.12 installed.
+
+To run the script, use the following commands:
+
+```{bash}
+chmod +x venv_setup.sh
+./venv_setup.sh
+```
+
+**Note:**
+The experiments involving the SMAC algorithm require the `smac` library, which in turn requires the building and compliling the `pyrfr` package While the main functions of `fcvopt` do not depend on `pyrfr`, you might encounter build issues during its installation if you do not have a C++ compiler and the `swig` binary installed on your system. 
+
+### Setting up a Docker container
+
+The Dockerfile is provided to run the experiments in a container with the `fcvopt` package and all the required dependencies. The Dockerfile is based on the Python 3.10 debian image. To build the image, run the following command:
+
+```{bash}
+docker build -t fcvopt_test .
+```
+
+To run the container with the files in the `experiments` folder mounted, run the following command:
+
+```{bash}
+docker run -v <path_to_experiments_folder>:/app/experiments -it fcvopt_test
+```
+
+This will launch the container and open a bash shell. The experiments directory will be mounted in the container at `/app/experiments`. Mounting the directory allows you to access the files in the experiments folder from within the container, and any changes made to the files will be reflected in your local directory. Replace <path_to_experiments_folder> with the **absolute path** to your local experiments directory.  Relative paths will not work, as the container will not have access to your local file system. On Linux and MacOS, you can use the $(pwd) command to get the absolute path of the current directory. For example:
+
+```{bash}
+docker run -v $(pwd)/experiments:/app/experiments -it fcvopt_test
+```
+
+Once inside the container, you can navigate to the /app/experiments directory and run the experiments as needed. For example:
+
+```{bash}
+cd experiments
+bash reproduce_rf.sh
+```
+
+**Note:** On Ubuntu/Debian, you may need administrative privileges to run the Docker commands. You can do this by adding `sudo` before the command.

fcvopt-0.4.0/README.md

@@ -0,0 +1,91 @@
+# fcvopt: Fractional cross-validation for hyperparameter optimization
+
+FCVOpt is a Python package for "Fractional Cross-Validation"in hyperparameter optimization. It implements efficient hyperparameter tuning by evaluating only a fraction of cross-validation folds using hierarchical Gaussian processes.
+
+The documentation is available at [https://syerramilli.github.io/fcvopt/](https://syerramilli.github.io/fcvopt/).
+
+🚀 **Key Features**:
+
+* **Efficient Optimization**: Evaluate hyperparameters using only a subset of CV folds
+* **Hierarchical Gaussian Processes**: Model fold-wise correlations for better predictions
+* **MLflow Integration**: Automatic experiment tracking and model versioning
+* **Framework Support**: Scikit-learn, XGBoost, PyTorch (via Skorch), and more
+
+## Installation
+
+### From Source
+
+```{bash}
+git clone https://github.com/syerramilli/fcvopt.git
+cd fcvopt
+pip install .
+```
+
+**With optional dependencies**:
+
+```{bash}
+pip install .[experiments]  # For reproducing the results from the paper
+pip install .[docs]         # For building documentation
+```
+
+## Citing
+If you use this code in your research, please cite the following paper:
+
+```
+@article{yerramilli2025fractional,
+    author = {Suraj Yerramilli and Daniel W. Apley},
+    title = {Fractional Cross-Validation for Optimizing Hyperparameters of Supervised Learning Algorithms},
+    journal = {Technometrics},
+    year = {2025},
+    doi = {10.1080/00401706.2025.2515926},
+}
+```
+
+## Reproducting the experiment results from the paper
+
+The experiments are all contained in the `experiments` folder. Each subdirectory within this folder contains scripts files to run each case study in the paper. Refer to the README file within each of the subdirectories for instructions to run the files.
+
+For reproducibility, we provide two options for setting up the environment to run the experiments: a virtual environment using `venv` and a Docker container.
+
+### Setting up a virtual environment
+
+The bash script file `venv_setup.sh` can be used to create a virtual environment and install the required packages. Ensure you have Python >= 3.8 and <=3.12 installed.
+
+To run the script, use the following commands:
+
+```{bash}
+chmod +x venv_setup.sh
+./venv_setup.sh
+```
+
+**Note:**
+The experiments involving the SMAC algorithm require the `smac` library, which in turn requires the building and compliling the `pyrfr` package While the main functions of `fcvopt` do not depend on `pyrfr`, you might encounter build issues during its installation if you do not have a C++ compiler and the `swig` binary installed on your system. 
+
+### Setting up a Docker container
+
+The Dockerfile is provided to run the experiments in a container with the `fcvopt` package and all the required dependencies. The Dockerfile is based on the Python 3.10 debian image. To build the image, run the following command:
+
+```{bash}
+docker build -t fcvopt_test .
+```
+
+To run the container with the files in the `experiments` folder mounted, run the following command:
+
+```{bash}
+docker run -v <path_to_experiments_folder>:/app/experiments -it fcvopt_test
+```
+
+This will launch the container and open a bash shell. The experiments directory will be mounted in the container at `/app/experiments`. Mounting the directory allows you to access the files in the experiments folder from within the container, and any changes made to the files will be reflected in your local directory. Replace <path_to_experiments_folder> with the **absolute path** to your local experiments directory.  Relative paths will not work, as the container will not have access to your local file system. On Linux and MacOS, you can use the $(pwd) command to get the absolute path of the current directory. For example:
+
+```{bash}
+docker run -v $(pwd)/experiments:/app/experiments -it fcvopt_test
+```
+
+Once inside the container, you can navigate to the /app/experiments directory and run the experiments as needed. For example:
+
+```{bash}
+cd experiments
+bash reproduce_rf.sh
+```
+
+**Note:** On Ubuntu/Debian, you may need administrative privileges to run the Docker commands. You can do this by adding `sudo` before the command.

fcvopt-0.4.0/docs/Makefile

@@ -0,0 +1,20 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = source
+BUILDDIR      = build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)