pyoframe 0.2.0__tar.gz → 1.0.0a0__tar.gz

{pyoframe-0.2.0 → pyoframe-1.0.0a0}/.github/actions/setup_optimizers_linux/action.yml

@@ -5,7 +5,7 @@
 name: "Install optimizers on linux"
 
 inputs:
-  GUROBI_WLS: 
+  GUROBI_WLS:
     description: "..."
     required: true
   # COPT_CLIENT_INI:
@@ -17,7 +17,7 @@ inputs:
   # GITHUB_TOKEN:
   #   description: "..."
   #   required: true
-  CHECK_LICENSE: 
+  CHECK_LICENSE:
     description: "..."
     required: true
 
@@ -33,18 +33,22 @@ runs:
       id: cache-installers-linux
       uses: actions/cache@v4
       env:
-        cache-name: cache-installers-linux
+        cache-name: cache-installers-linux-v2
       with:
         path: ~/installers
-        key: ${{ runner.os }}-build-${{ env.cache-name }}-${{ hashFiles('optimizer_version.toml') }}
+        key: ${{ runner.os }}-build-${{ env.cache-name }}-v2-${{ hashFiles('optimizer_version.toml') }}
         restore-keys: |
-          ${{ runner.os }}-build-${{ env.cache-name }}-
+          ${{ runner.os }}-build-${{ env.cache-name }}-v2-
 
-    - if: ${{ steps.cache-installers-linux.outputs.cache-hit != 'true' }}
+    - if: ${{ steps.cache-installers-linux-v2.outputs.cache-hit != 'true' }}
       shell: bash
       name: Download Installers
       run: |
         curl -L -o ~/installers/gurobi.tar.gz https://packages.gurobi.com/12.0/gurobi12.0.2_linux64.tar.gz
+        curl -L -o ~/installers/idaes-solvers.tar.gz https://github.com/IDAES/idaes-ext/releases/download/3.4.2/idaes-solvers-ubuntu2204-x86_64.tar.gz
+
+    # curl -L -o ~/installers/copt.tar.gz https://pub.shanshu.ai/download/copt/7.2.8/linux64/CardinalOptimizer-7.2.8-lnx64.tar.gz
+    # curl -L -o ~/installers/mosek.tar.bz2 https://download.mosek.com/stable/10.2.0/mosektoolslinux64x86.tar.bz2
 
     - name: Setup Gurobi Installation
       shell: bash
@@ -59,13 +63,13 @@ runs:
         echo "PATH=${PATH}:${GUROBI_HOME}/bin" >> $GITHUB_ENV
         echo "LD_LIBRARY_PATH=${LD_LIBRARY_PATH}:${GUROBI_HOME}/lib" >> $GITHUB_ENV
         echo $GUROBI_HOME
-        
+
         # setup license using secrets
         echo "$GUROBI_WLS" > ~/gurobi.lic
         echo "GRB_LICENSE_FILE=${HOME}/gurobi.lic" >> $GITHUB_ENV
     - name: Test Gurobi
       if: ${{ inputs.CHECK_LICENSE == 'true' }}
-      uses: nick-fields/retry@v3    # wait 30 seconds (5x) if all licenses are already in use
+      uses: nick-fields/retry@v3 # wait 30 seconds (5x) if all licenses are already in use
       with:
         max_attempts: 5
         retry_wait_seconds: 30
@@ -118,15 +122,16 @@ runs:
     #   run: |
     #     msktestlic
 
-    # - name: Setup IPOPT Installation
-    #   shell: bash
-    #   run: |
-    #     mkdir -p ~/ipopt
-    #     tar xfz ~/installers/idaes-solvers.tar.gz -C ~/ipopt
-    #     echo "PATH=${PATH}:${HOME}/ipopt" >> $GITHUB_ENV
-    #     echo "LD_LIBRARY_PATH=${LD_LIBRARY_PATH}:${HOME}/ipopt" >> $GITHUB_ENV
-    #     ls ~/ipopt
-    # - name: Test IPOPT
-    #   shell: bash
-    #   run: |
-    #     ipopt -v
+    - name: Setup IPOPT Installation
+      shell: bash
+      run: |
+        sudo apt-get install -y libopenblas-dev liblapack3 libgfortran5
+        mkdir -p ~/ipopt
+        tar xfz ~/installers/idaes-solvers.tar.gz -C ~/ipopt
+        echo "PATH=${PATH}:${HOME}/ipopt" >> $GITHUB_ENV
+        echo "LD_LIBRARY_PATH=${LD_LIBRARY_PATH}:${HOME}/ipopt" >> $GITHUB_ENV
+        ls ~/ipopt
+    - name: Test IPOPT
+      shell: bash
+      run: |
+        ipopt -v

{pyoframe-0.2.0 → pyoframe-1.0.0a0}/.github/workflows/ci.yml

@@ -1,3 +1,8 @@
+# This workflow runs the tests.
+# It is triggered automatically on pull requests and is also run weekly on the main branch.
+# Tests are run in a matrix of different Python versions.
+# This test also uploads coverage results to Codecov.
+
 # Note: We use the insecure pull_request_target to allow running workflows from forks.
 # However, we've added checks (see below) for safety.
 # In short, the 'safe to test' label must exist AND the workflow must be run by someone with write access.
@@ -75,13 +80,12 @@ jobs:
         with:
           python-version: ${{ matrix.python-version }}
           cache: "pip"
+      - name: Install dependencies
+        run: pip install -e .[dev]
       - uses: ./.github/actions/setup_optimizers_linux
         with:
           GUROBI_WLS: ${{ secrets.GUROBI_WLS }}
           CHECK_LICENSE: true
-      - name: Install dependencies
-        run: |
-          pip install --editable .[dev]
       - name: Run tests and collect coverage
         run: pytest --cov
       - name: Upload coverage to Codecov

{pyoframe-0.2.0 → pyoframe-1.0.0a0}/.github/workflows/format.yml

@@ -1,3 +1,4 @@
+# This workflow ensures that `ruff check` passes on pull requests.
 name: Check formatting with Ruff
 
 on: [pull_request]

{pyoframe-0.2.0 → pyoframe-1.0.0a0}/.github/workflows/lines_changed_counter.yml

@@ -1,3 +1,5 @@
+# This workflow adds a comment to pull requests with the number of lines added, deleted, and changed.
+
 # MIT License
 # Copyright (c) 2021 Viacheslav Poturaev
 name: Comment on PR with lines changed

{pyoframe-0.2.0 → pyoframe-1.0.0a0}/.github/workflows/lint.yml

@@ -1,3 +1,4 @@
+# This workflow ensures that `ruff format` passes on pull requests.
 name: Check linting with Ruff
 on: [pull_request]
 

pyoframe-1.0.0a0/.github/workflows/publish_doc.yml

@@ -0,0 +1,54 @@
+# This workflow runs every time a new tag is released and publishes the documentation to the website.
+name: Docs
+on:
+  workflow_dispatch:
+  release:
+    types: [released]
+env:
+  ENABLED_GIT_REVISION_DATE: true
+  ENABLED_GIT_COMMITTERS: true
+  DOCS_PRERELEASE: false
+permissions:
+  contents: write
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    environment: build-docs
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0  # Needed for git-revision-date-localized plugin
+          fetch-tags: true
+      - name: Configure Git Credentials
+        run: |
+          git config user.name github-actions[bot]
+          git config user.email 41898282+github-actions[bot]@users.noreply.github.com
+      - uses: actions/setup-python@v5
+        with:
+          python-version: 3.x
+          cache: 'pip'
+      - run: echo "cache_id=$(date --utc '+%V')" >> $GITHUB_ENV 
+      - uses: actions/cache@v4
+        with:
+          key: mkdocs-material-${{ env.cache_id }}
+          path: .cache
+          restore-keys: |
+            mkdocs-material-
+      - run: pip install .[docs]
+      - name: Get latest tag
+        id: tags
+        run: |
+          # Get the latest tag like v1.2.3, remove the leading 'v' if present, and remove the patch version
+          latest_tag=$(git describe --tags --abbrev=0)
+          clean_tag=${latest_tag#v}
+          minor_tag=$(echo "$clean_tag" | cut -d. -f1-2)
+
+          echo "latest_tag=$latest_tag" >> $GITHUB_ENV
+          echo "minor_tag=$minor_tag" >> $GITHUB_ENV
+      # Some examples
+      # https://github.com/squidfunk/mkdocs-material/discussions/6546
+      # https://github.com/arduino/arduino-cli/blob/master/.github/workflows/deploy-cobra-mkdocs-versioned-poetry.yml
+      # https://blog.grosdouli.dev/blog/mkdocs-mike-integration#setup-github-workflows
+      - run: mike deploy --update-aliases --push --title $latest_tag $minor_tag latest
+        env:
+          MKDOCS_GIT_COMMITTERS_APIKEY : ${{ secrets.MKDOCS_GIT_COMMITTERS_APIKEY }}

pyoframe-1.0.0a0/.github/workflows/publish_doc_dev.yml

@@ -0,0 +1,43 @@
+# This workflow runs on every commit to main and publishes a development version of the documentation to the website.
+name: Publish dev docs
+on:
+  workflow_dispatch:
+  push:
+    branches: [main]
+env:
+  ENABLED_GIT_REVISION_DATE: true
+  ENABLED_GIT_COMMITTERS: true
+  DOCS_PRERELEASE: true
+permissions:
+  contents: write
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    environment: build-docs
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0 # Needed for git-revision-date-localized plugin
+      - name: Configure Git Credentials
+        run: |
+          git config user.name github-actions[bot]
+          git config user.email 41898282+github-actions[bot]@users.noreply.github.com
+      - uses: actions/setup-python@v5
+        with:
+          python-version: 3.x
+          cache: "pip"
+      - run: echo "cache_id=$(date --utc '+%V')" >> $GITHUB_ENV
+      - uses: actions/cache@v4
+        with:
+          key: mkdocs-material-${{ env.cache_id }}
+          path: .cache
+          restore-keys: |
+            mkdocs-material-
+      - run: pip install .[docs]
+      # Some examples
+      # https://github.com/squidfunk/mkdocs-material/discussions/6546
+      # https://github.com/arduino/arduino-cli/blob/master/.github/workflows/deploy-cobra-mkdocs-versioned-poetry.yml
+      # https://blog.grosdouli.dev/blog/mkdocs-mike-integration#setup-github-workflows
+      - run: mike deploy --push dev
+        env:
+          MKDOCS_GIT_COMMITTERS_APIKEY: ${{ secrets.MKDOCS_GIT_COMMITTERS_APIKEY }}

{pyoframe-0.2.0 → pyoframe-1.0.0a0}/.github/workflows/publish_to_pypi.yml

@@ -1,3 +1,4 @@
+# This workflow runs when a new release is published and uploads the package to PyPI.
 name: PyPi Publishing
 
 on:

pyoframe-1.0.0a0/.github/workflows/test_doc.yml

@@ -0,0 +1,23 @@
+# This workflow runs on pull requests and tests that building the docs works
+name: Test documentation builds
+on:
+  pull_request:
+    branches: ["*"]
+jobs:
+  run:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: 3.x
+          cache: "pip"
+      - run: echo "cache_id=$(date --utc '+%V')" >> $GITHUB_ENV
+      - uses: actions/cache@v4
+        with:
+          key: mkdocs-material-${{ env.cache_id }}
+          path: .cache
+          restore-keys: |
+            mkdocs-material-
+      - run: pip install .[docs]
+      - run: mkdocs build --strict

{pyoframe-0.2.0 → pyoframe-1.0.0a0}/.gitignore

@@ -7,10 +7,10 @@ build
 tmp
 .coverage
 .cache
-docs/reference
 dist
 *.log
 site
 .idea
 src/pyoframe/_version.py
 htmlcov/
+.snakemake

pyoframe-1.0.0a0/.pre-commit-config.yaml

@@ -0,0 +1,15 @@
+repos:
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    # Ruff version.
+    rev: v0.12.7
+    hooks:
+      # Run the linter.
+      - id: ruff-check
+        args: [ --fix ]
+      # Run the formatter.
+      - id: ruff-format
+  - repo: https://github.com/adamtheturtle/doccmd-pre-commit
+    rev: v2025.4.8
+    hooks:
+    -   id: doccmd
+        args: ["--language", "python", "--no-pad-file", "--command", "ruff format", "docs/"]

pyoframe-1.0.0a0/.vscode/launch.json

@@ -0,0 +1,17 @@
+{
+    // Use IntelliSense to learn about possible attributes.
+    // Hover to view descriptions of existing attributes.
+    // For more information, visit: https://go.microsoft.com/fwlink/?linkid=830387
+    "version": "0.2.0",
+    "configurations": [
+        {
+            "name": "Debug mkdocs",
+            "type": "debugpy",
+            "request": "launch",
+            "module": "mkdocs",
+            "args": [
+                "serve"
+            ]
+        }
+    ]
+}

pyoframe-1.0.0a0/.vscode/settings.json

@@ -0,0 +1,14 @@
+{
+    "python.testing.unittestEnabled": false,
+    "python.testing.pytestEnabled": true,
+    "cSpell.words": [
+        "dataframes",
+        "Gurobi",
+        "highs",
+        "ipopt",
+        "Pyoframe"
+    ],
+    "python.testing.pytestArgs": [
+        "."
+    ]
+}

{pyoframe-0.2.0 → pyoframe-1.0.0a0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pyoframe
-Version: 0.2.0
+Version: 1.0.0a0
 Summary: Blazing fast linear program interface
 Author-email: Bravos Power <dev@bravospower.com>
 License-Expression: MIT
@@ -20,30 +20,37 @@ Requires-Dist: numpy
 Requires-Dist: pyarrow
 Requires-Dist: pandas
 Requires-Dist: pyoptinterface<1,>=0.4.1
-Provides-Extra: dev
-Requires-Dist: ruff; extra == "dev"
-Requires-Dist: polars>=1.30.0; extra == "dev"
-Requires-Dist: bumpver; extra == "dev"
-Requires-Dist: pip-tools; extra == "dev"
-Requires-Dist: pytest; extra == "dev"
-Requires-Dist: pytest-cov; extra == "dev"
-Requires-Dist: pre-commit; extra == "dev"
-Requires-Dist: gurobipy; extra == "dev"
-Requires-Dist: highsbox; extra == "dev"
-Requires-Dist: coverage; extra == "dev"
-Requires-Dist: ipykernel; extra == "dev"
-Requires-Dist: pytest-markdown-docs; extra == "dev"
-Requires-Dist: mkdocs-material==9.*; extra == "dev"
-Requires-Dist: mkdocstrings[python]; extra == "dev"
-Requires-Dist: mkdocs-git-revision-date-localized-plugin; extra == "dev"
-Requires-Dist: mkdocs-git-committers-plugin-2; extra == "dev"
-Requires-Dist: mkdocs-gen-files; extra == "dev"
-Requires-Dist: mkdocs-section-index; extra == "dev"
-Requires-Dist: mkdocs-literate-nav; extra == "dev"
-Requires-Dist: mkdocs-table-reader-plugin; extra == "dev"
-Requires-Dist: markdown-hide-code>=0.1.1; extra == "dev"
 Provides-Extra: highs
 Requires-Dist: highsbox; extra == "highs"
+Provides-Extra: ipopt
+Requires-Dist: pyoptinterface[nlp]; extra == "ipopt"
+Requires-Dist: llvmlite<=0.44.0; extra == "ipopt"
+Provides-Extra: dev
+Requires-Dist: ruff==0.12.11; extra == "dev"
+Requires-Dist: polars>=1.32.3; extra == "dev"
+Requires-Dist: pytest==8.4.1; extra == "dev"
+Requires-Dist: pytest-cov==6.2.1; extra == "dev"
+Requires-Dist: sybil[pytest]==9.2.0; extra == "dev"
+Requires-Dist: pre-commit==4.3.0; extra == "dev"
+Requires-Dist: gurobipy==12.0.3; extra == "dev"
+Requires-Dist: coverage==7.10.6; extra == "dev"
+Requires-Dist: ipykernel==6.30.1; extra == "dev"
+Requires-Dist: highsbox; extra == "dev"
+Requires-Dist: pyoptinterface[nlp]; extra == "dev"
+Requires-Dist: llvmlite<=0.44.0; extra == "dev"
+Provides-Extra: docs
+Requires-Dist: mkdocs-material~=9.6.18; extra == "docs"
+Requires-Dist: mkdocstrings[python]~=0.30.0; extra == "docs"
+Requires-Dist: mkdocs-git-revision-date-localized-plugin~=1.4.7; extra == "docs"
+Requires-Dist: mkdocs-git-committers-plugin-2~=2.5.0; extra == "docs"
+Requires-Dist: mkdocs-gen-files~=0.5.0; extra == "docs"
+Requires-Dist: mkdocs-section-index~=0.3.10; extra == "docs"
+Requires-Dist: mkdocs-awesome-nav~=3.1.2; extra == "docs"
+Requires-Dist: doccmd==2025.4.8; extra == "docs"
+Requires-Dist: mkdocs-table-reader-plugin~=3.1.0; extra == "docs"
+Requires-Dist: markdown-katex==202406.1035; extra == "docs"
+Requires-Dist: mike==2.1.3; extra == "docs"
+Requires-Dist: ruff==0.12.11; extra == "docs"
 Dynamic: license-file
 
 # Pyoframe: Fast and low-memory linear programming models 
@@ -56,11 +63,11 @@ Dynamic: license-file
 [![Open Bugs](https://img.shields.io/github/issues-search/Bravos-Power/pyoframe?query=label%3Abug%20is%3Aopen&label=Open%20Bugs)](https://github.com/Bravos-Power/pyoframe/issues?q=is%3Aopen+is%3Aissue+label%3Abug)
 
 
-A library to rapidly and memory-efficiently formulate large and sparse optimization models using Pandas or Polars dataframes.
+A library to rapidly and memory-efficiently formulate large and sparse optimization models using Pandas or Polars DataFrames.
 
 ## **[Documentation](https://bravos-power.github.io/pyoframe/)**
 
-[Read the documentation](https://bravos-power.github.io/pyoframe/) to get started or to learn how to [contribute](https://bravos-power.github.io/pyoframe/contribute/).
+[Read the documentation](https://bravos-power.github.io/pyoframe/) to get started or to learn how to [contribute](https://bravos-power.github.io/pyoframe/contribute/index.md).
 
 
 ## Acknowledgments

{pyoframe-0.2.0 → pyoframe-1.0.0a0}/README.md

@@ -8,11 +8,11 @@
 [![Open Bugs](https://img.shields.io/github/issues-search/Bravos-Power/pyoframe?query=label%3Abug%20is%3Aopen&label=Open%20Bugs)](https://github.com/Bravos-Power/pyoframe/issues?q=is%3Aopen+is%3Aissue+label%3Abug)
 
 
-A library to rapidly and memory-efficiently formulate large and sparse optimization models using Pandas or Polars dataframes.
+A library to rapidly and memory-efficiently formulate large and sparse optimization models using Pandas or Polars DataFrames.
 
 ## **[Documentation](https://bravos-power.github.io/pyoframe/)**
 
-[Read the documentation](https://bravos-power.github.io/pyoframe/) to get started or to learn how to [contribute](https://bravos-power.github.io/pyoframe/contribute/).
+[Read the documentation](https://bravos-power.github.io/pyoframe/) to get started or to learn how to [contribute](https://bravos-power.github.io/pyoframe/contribute/index.md).
 
 
 ## Acknowledgments

pyoframe-1.0.0a0/conftest.py

@@ -0,0 +1,93 @@
+"""File related to setting up pytest."""
+
+import doctest
+import os
+import warnings
+from pathlib import Path
+
+import polars as pl
+import pytest
+
+import pyoframe as pf
+
+
+def _setup_before_each_test(doctest_namespace):
+    doctest_namespace["pf"] = pf
+    pf.Config.reset_defaults()
+    pf.Config.enable_is_duplicated_expression_safety_check = True
+
+
+@pytest.fixture(autouse=True)
+def _setup_fixture(doctest_namespace):
+    _setup_before_each_test(doctest_namespace)
+
+
+def pytest_collection_modifyitems(items):
+    """Exclude certain paths from contributing to the test coverage.
+
+    Specifically, the integration tests and documentation code snippets are not
+    counted towards the coverage metrics because they're not rigorous enough.
+
+    See:
+        - https://docs.pytest.org/en/stable/reference/reference.html#pytest.hookspec.pytest_collection_modifyitems
+        - https://stackoverflow.com/questions/60608511/pytest-cov-dont-count-coverage-for-the-directory-of-integration-tests
+    """
+    root_dir = Path(__file__).parent
+    no_coverage_paths = (
+        root_dir / "docs",
+        root_dir / "tests" / "test_examples.py",
+    )
+
+    for item in items:
+        test_path = Path(item.fspath)
+        if any(test_path.is_relative_to(p) for p in no_coverage_paths):
+            item.add_marker(pytest.mark.no_cover)
+
+
+@pytest.fixture(scope="module")
+def markdown_setup_fixture_module():
+    cwd = os.getcwd()
+    yield
+    os.chdir(cwd)
+
+
+@pytest.fixture
+def markdown_setup_fixture():
+    pl.Config.restore_defaults()
+    pl.Config.set_tbl_hide_dataframe_shape(True)
+    yield
+    pl.Config.set_tbl_hide_dataframe_shape(False)
+
+
+SYBIL = False
+try:
+    from sybil import Sybil
+    from sybil.evaluators.doctest import NUMBER
+    from sybil.parsers.markdown import (
+        ClearNamespaceParser,
+        PythonCodeBlockParser,
+        SkipParser,
+    )
+    from sybil.parsers.rest import DocTestParser
+
+    SYBIL = True
+except ImportError:
+    # Sybil is not installed, so we won't collect markdown files.
+    pass
+
+if SYBIL:
+    pytest_collect_file = Sybil(
+        parsers=[
+            PythonCodeBlockParser(),
+            SkipParser(),
+            ClearNamespaceParser(),
+            DocTestParser(
+                optionflags=doctest.ELLIPSIS | NUMBER | doctest.NORMALIZE_WHITESPACE
+            ),
+        ],
+        patterns=["*.md"],
+        setup=_setup_before_each_test,
+        fixtures=["markdown_setup_fixture", "markdown_setup_fixture_module"],
+    ).pytest()
+else:
+    warnings.warn("Sybil not installed. Documentation tests will not run.")

pyoframe-1.0.0a0/docs/.nav.yml

@@ -0,0 +1,13 @@
+sort:
+  by: filename
+nav:
+  - Home: index.md
+  - Learn:
+    - learn/get-started
+    - learn/concepts
+    - learn/advanced-concepts
+    - learn/migrate
+  - examples
+  - reference
+  - why-pyoframe/index.md
+  - contribute

pyoframe-1.0.0a0/docs/contribute/index.md

@@ -0,0 +1,51 @@
+---
+hide:
+  - navigation
+---
+# Contribute
+
+Contributions are more than welcome! Submit a pull request, or [open an issue](https://github.com/Bravos-Power/pyoframe/issues/new) and I (Martin) will gladly answer your questions on how to contribute.
+
+## Setup a development environment
+
+1. Clone this repository.
+```console
+git clone https://github.com/Bravos-Power/pyoframe
+```
+
+2. Install the dependencies. 
+```console
+pip install --editable .[dev,docs]
+```
+
+3. Install the pre-commit hooks. 
+```console
+pre-commit install
+```
+
+4. Run `pytest` to make sure everything is working. The only errors you should see are those related to a solver not being installed. If not, [open an issue](https://github.com/Bravos-Power/pyoframe/issues/new)!
+
+## Writing documentation
+
+We use [Material Docs](https://squidfunk.github.io/mkdocs-material/) for documentation with several plugins to enable features like automatically compiling the docstrings into the reference API. Please follow the [Google docstring style](https://sphinxcontrib-napoleon.readthedocs.io/en/latest/example_google.html) and the [Google style guide](https://developers.google.com/style). Additionally, all Python code blocks in Markdown files are tested using Sybil. To properly setup the tests refer to this [Sybil documentation](https://sybil.readthedocs.io/en/latest/markdown.html#code-blocks).
+
+## Helpful commands
+
+- `pytest`: Runs all the tests. If you'd like to generate coverage information just add the flag `--cov`.
+- `mkdocs serve`: Generates the documentation locally. Navigate to [`http://127.0.0.1:8000/pyoframe/`](http://127.0.0.1:8000/pyoframe/) to check it out.
+- `coverage html`: Generate a webpage to view the coverage information generated after having run `pytest --cov`.
+- `python -m tests.test_examples`: Regenerate the files in the `results` folder of an example (e.g. `tests/examples/sudoku/results/**`). You should only run this if the result files need to be regenerated, for example, if model variable names have changed.
+- `ruff check`: Ensures all the linter tests pass
+- `ruff format`: Ensures the code is properly formatted (this is run upon commit if you've installed the pre-commit hooks)
+- `doccmd --language=python --no-pad-file --command="ruff format" docs/`: to format the code in the documentation.
+- `mike serve` to see a local version of the documentation with the version selector.
+
+## Additional tips
+
+- If you use `.unique`, `.join`, `.sort`, or `.group_by` on a Polars dataframe, make sure to set the `maintain_order` parameter appropriately (typically, `maintain_order=Config.maintain_order`).
+
+## Details for repository maintainers
+
+### Expired Gurobi License
+
+We use a Gurobi license to run our tests. If the tests fail an give a license expired error, generate a new one and copy the contents of the `guorbi.lic` file into the `GUROBI_WLS` Github secret (Settings -> Secrets and variables -> actions).

pyoframe-1.0.0a0/docs/examples/.nav.yml

@@ -0,0 +1,6 @@
+nav:
+  - index.md
+  - diet.md
+  - production.md
+  - facility_location.md
+  - portfolio_optimization.md

pyoframe-1.0.0a0/docs/examples/diet.md

@@ -0,0 +1,68 @@
+# Diet problem
+
+## Problem statement
+
+Given a list of potential foods, their costs, and their availability ([`foods.csv`](https://github.com/Bravos-Power/pyoframe/blob/main/tests/examples/diet_problem/input_data/foods.csv)), and a list of the nutrients (e.g., protein, fats, etc.) contained in each food ([`foods_to_nutrients.csv`](https://github.com/Bravos-Power/pyoframe/blob/main/tests/examples/diet_problem/input_data/foods_to_nutrients.csv)), how can you satisfy your dietary requirements ([`nutrients.csv`](https://github.com/Bravos-Power/pyoframe/blob/main/tests/examples/diet_problem/input_data/nutrients.csv)) while minimizing total costs?
+
+## Model
+
+<!-- invisible-code-block: python
+import os
+
+os.chdir(os.path.join(os.getcwd(), "tests/examples/diet_problem/input_data"))
+-->
+
+```python
+import pandas as pd
+
+import pyoframe as pf
+
+# Import data
+food = pd.read_csv("foods.csv")
+nutrients = pd.read_csv("nutrients.csv")
+food_nutrients = pd.read_csv("foods_to_nutrients.csv")
+
+# Construct model
+m = pf.Model()
+m.Buy = pf.Variable(food["food"], lb=0, ub=food[["food", "stock"]])
+
+nutrient_intake = (m.Buy * food_nutrients).sum_by("category")
+m.min_nutrients = (
+    nutrients[["category", "min"]] <= nutrient_intake.drop_unmatched()  # (1)!
+)
+m.max_nutrients = nutrient_intake.drop_unmatched() <= nutrients[["category", "max"]]
+
+total_cost = (m.Buy * food[["food", "cost"]]).sum()
+m.minimize = total_cost
+
+# Solve model
+m.optimize()
+```
+
+1. `.drop_unmatched()` ensures that if `min_nutrient` is `null` for certain foods, no constraint will be created for those foods. [Learn more](../learn/concepts/special-functions.md#drop_unmatched-and-keep_unmatched)
+
+So the solution is...
+
+```pycon
+>>> total_cost.evaluate()
+12.060249999999998
+>>> m.Buy.solution
+┌───────────┬──────────┐
+│ food      ┆ solution │
+│ ---       ┆ ---      │
+│ str       ┆ f64      │
+╞═══════════╪══════════╡
+│ hamburger ┆ 0.555263 │
+│ chicken   ┆ 0.0      │
+│ hot_dog   ┆ 0.0      │
+│ fries     ┆ 0.0      │
+│ macaroni  ┆ 0.0      │
+│ pizza     ┆ 0.0      │
+│ salad     ┆ 0.0      │
+│ milk      ┆ 6.8      │
+│ ice_cream ┆ 2.909211 │
+└───────────┴──────────┘
+
+```
+
+Not a very balanced diet :thinking:.