example.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "id": "6df23cfb-cd15-4024-9810-ff240b1f2444",
   "metadata": {},
   "source": [
    "# Example notebook for the PSPLIB Python package"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "b332249a-04e2-4d73-8c48-0b09d4276245",
   "metadata": {},
   "source": [
    "This notebook demonstrates how to use the PSPLIB Python package for parsing different project scheduling formats, highlighting the differences between the resulting output.\n",
    "All parsers return an instance of the [`ProjectInstance`](https://github.com/PyJobShop/PSPLIB/blob/main/psplib/ProjectInstance.py) class. \n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "id": "4fec4d5b-df0f-48c4-9e55-602203a89176",
   "metadata": {},
   "outputs": [],
   "source": [
    "from psplib import parse"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "39f3899e-cb96-4c24-80d9-f436abfb9031",
   "metadata": {},
   "source": [
    "## PSPLIB format"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "72f3c46b-b490-4a7c-bcd3-5e4342b98e17",
   "metadata": {},
   "source": [
    "PSPLIB is a standard format for resource-constrained project scheduling problems (RCPSPs)."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "id": "0530bec2-580c-4845-a1f7-8f94d69a5f40",
   "metadata": {},
   "outputs": [],
   "source": [
    "instance = parse(\"data/j301_1.sm\", instance_format=\"psplib\")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "bb155e39-1a31-430c-8352-0206fd998be2",
   "metadata": {},
   "source": [
    "Get basic instance information: number of resources and activities"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "id": "bfbca94a-720a-4873-b1b7-3c0a52d2a5b0",
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "(4, 32)"
      ]
     },
     "execution_count": 3,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "(instance.num_resources, instance.num_activities)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "b9518b54-eb11-48b0-b410-15bb15094b39",
   "metadata": {},
   "source": [
    "Resource have a capacity and renewable status."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "id": "e2f6acd6-f529-4833-b479-e00550584820",
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "[Resource(capacity=12, renewable=True, skills=None),\n",
       " Resource(capacity=13, renewable=True, skills=None),\n",
       " Resource(capacity=4, renewable=True, skills=None),\n",
       " Resource(capacity=12, renewable=True, skills=None)]"
      ]
     },
     "execution_count": 4,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "instance.resources"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "d8647312-9885-4b2d-8ea9-42bf39790b24",
   "metadata": {},
   "source": [
    "Activities have modes, successors and possible delays (for RCPSP/max)."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 5,
   "id": "8a1235ac-d44f-4d01-9081-dfb7778c2fc7",
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "[Activity(modes=[Mode(duration=0, demands=[0, 0, 0, 0], skill_requirements=None)], successors=[1, 2, 3], delays=None, optional=False, selection_groups=[], name=''),\n",
       " Activity(modes=[Mode(duration=8, demands=[4, 0, 0, 0], skill_requirements=None)], successors=[5, 10, 14], delays=None, optional=False, selection_groups=[], name=''),\n",
       " Activity(modes=[Mode(duration=4, demands=[10, 0, 0, 0], skill_requirements=None)], successors=[6, 7, 12], delays=None, optional=False, selection_groups=[], name=''),\n",
       " Activity(modes=[Mode(duration=6, demands=[0, 0, 0, 3], skill_requirements=None)], successors=[4, 8, 9], delays=None, optional=False, selection_groups=[], name='')]"
      ]
     },
     "execution_count": 5,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "instance.activities[:4]"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "80b80efb-188b-410f-9e58-044e949aee58",
   "metadata": {},
   "source": [
    "A mode is a single processing option for a given activity, which includes duration and demand per resource."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 6,
   "id": "33dec608-c15c-4b7b-894d-0a6f67d8dafc",
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "[Mode(duration=0, demands=[0, 0, 0, 0], skill_requirements=None)]"
      ]
     },
     "execution_count": 6,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "instance.activities[0].modes"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "dc032dde-2e61-4fa7-a840-cd941cca1c15",
   "metadata": {},
   "source": [
    "## Patterson format"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "7af1a6b0-08ca-4a15-9674-40ae98ca7644",
   "metadata": {},
   "source": [
    "The Patterson format is another format for RCPSP instances.\n",
    "The concent of the instance is identical to the ones from PSPLIB."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 7,
   "id": "7c44dee1-a7d8-4c5f-9d5c-9dc119bb597d",
   "metadata": {},
   "outputs": [],
   "source": [
    "instance = parse(\"data/RG300_1.rcp\", instance_format=\"patterson\")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "f260a7a1-99f6-48a9-b6d3-3af111b5297e",
   "metadata": {},
   "source": [
    "## RCPSP/max format"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "3457807b-2e4a-404d-9ab3-6da5a70fa301",
   "metadata": {},
   "source": [
    "RCPSP/max instances introduce delays for each successor."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 8,
   "id": "2a0012ed-f019-4aaf-85b3-93241d380401",
   "metadata": {},
   "outputs": [],
   "source": [
    "instance = parse(\"data/UBO10_01.sch\", instance_format=\"rcpsp_max\")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "64fb639d-93dc-4c35-9ad1-e17fbd86f160",
   "metadata": {},
   "source": [
    "Note that the additional `delays` field is not empty, which specifies the time lag for each successor."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 9,
   "id": "6cdb8e24-587f-4b4b-b836-d808a3ecbe3e",
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "[Activity(modes=[Mode(duration=0, demands=[0, 0, 0, 0, 0], skill_requirements=None)], successors=[3, 2, 1, 8], delays=[0, 0, 0, 0], optional=False, selection_groups=[], name=''),\n",
       " Activity(modes=[Mode(duration=2, demands=[5, 7, 8, 4, 6], skill_requirements=None)], successors=[10], delays=[2], optional=False, selection_groups=[], name=''),\n",
       " Activity(modes=[Mode(duration=9, demands=[10, 8, 0, 8, 10], skill_requirements=None)], successors=[4, 11, 7], delays=[5, 9, 0], optional=False, selection_groups=[], name=''),\n",
       " Activity(modes=[Mode(duration=6, demands=[9, 9, 0, 4, 5], skill_requirements=None)], successors=[9], delays=[3], optional=False, selection_groups=[], name='')]"
      ]
     },
     "execution_count": 9,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "instance.activities[:4]"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "75604156-3c21-402d-a554-4aeeecd1a38b",
   "metadata": {},
   "source": [
    "## MPLIB format"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "42d677c0-9e7e-421d-a843-aec7cd9e137b",
   "metadata": {},
   "source": [
    "Multi-project RCPSP handles multiple projects with shared resources."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 10,
   "id": "3280aeae-0bcd-4faa-8649-6a8b64db4e5e",
   "metadata": {},
   "outputs": [],
   "source": [
    "instance = parse(\"data/MPLIB1_Set1_0.rcmp\", instance_format=\"mplib\")"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 11,
   "id": "f3d65f88-1840-4665-abcb-3d1fd3ae46da",
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "(4, 372, 6)"
      ]
     },
     "execution_count": 11,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "(instance.num_resources, instance.num_activities, instance.num_projects)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "39662193-2222-43e6-b2de-148f0ec3af9a",
   "metadata": {},
   "source": [
    "Each project contains a list of activity indices that belong to the project, and a common release date."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 12,
   "id": "67e3f2ad-8aed-47fe-9a43-cbe7159a585d",
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "[Project(activities=[0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20, 21, 22, 23, 24, 25, 26, 27, 28, 29, 30, 31, 32, 33, 34, 35, 36, 37, 38, 39, 40, 41, 42, 43, 44, 45, 46, 47, 48, 49, 50, 51, 52, 53, 54, 55, 56, 57, 58, 59, 60, 61], release_date=0, due_date=None),\n",
       " Project(activities=[62, 63, 64, 65, 66, 67, 68, 69, 70, 71, 72, 73, 74, 75, 76, 77, 78, 79, 80, 81, 82, 83, 84, 85, 86, 87, 88, 89, 90, 91, 92, 93, 94, 95, 96, 97, 98, 99, 100, 101, 102, 103, 104, 105, 106, 107, 108, 109, 110, 111, 112, 113, 114, 115, 116, 117, 118, 119, 120, 121, 122, 123], release_date=0, due_date=None)]"
      ]
     },
     "execution_count": 12,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "instance.projects[:2]"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "0d50356a-172d-4086-95e0-afd838ea7c56",
   "metadata": {},
   "source": [
    "## RCPSP-PS and ASLIB format\n",
    "In the RCPSP with flexible project structures (RCPSP-PS), there are choices about which activities to schedule.\n",
    "\n",
    "1. Activities can be optional - they don't all need to be scheduled\n",
    "2. Activities each have a set of associated selection groups\n",
    "3. If an activity is scheduled, then for each selection group, exactly one activity must also be scheduled"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "ba6e61af-bd49-4871-b932-a78e23d24e0b",
   "metadata": {},
   "source": [
    "Our library support two common RCPSP-PS formats."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "a915ad69-962b-43f4-bc99-002739bb7eb8",
   "metadata": {},
   "source": [
    "### RCPSP-PS"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "68832a0e-eca0-407e-ad3b-dad79bc72cc4",
   "metadata": {},
   "source": [
    "The \"RCPSP-PS\" format is the format used by [Van der Beek et al. (2024)](https://www.sciencedirect.com/science/article/pii/S0377221724008269)."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 13,
   "id": "c7b74459-6107-4e88-a729-7f0cc7d7f76f",
   "metadata": {},
   "outputs": [],
   "source": [
    "instance = parse(\"data/rcpsp_ps.txt\", instance_format=\"rcpsp_ps\")"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 14,
   "id": "bebe5e60-c84a-45c4-a9ef-9d7f34eed561",
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "(4, 136)"
      ]
     },
     "execution_count": 14,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "(instance.num_resources, instance.num_activities)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 15,
   "id": "990c6936-cbf2-47c4-823d-35fbdc2c240f",
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "Activity(modes=[Mode(duration=0, demands=[0, 0, 0, 0], skill_requirements=None)], successors=[1, 2], delays=None, optional=False, selection_groups=[[1, 2]], name='')"
      ]
     },
     "execution_count": 15,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "activity = instance.activities[0]  # source\n",
    "activity"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "529e7add-9c25-4a41-b44b-4fda01f2f5d0",
   "metadata": {},
   "source": [
    "The source activity must always be present (`optional=False`).\n",
    "It has one selection group consisting of activities 1 and 2.\n",
    "This means that either activity 1 or activity 2 must be scheduled."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 16,
   "id": "1cb5b8c1-a6f3-4297-a327-fb2b4f05a927",
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "Activity(modes=[Mode(duration=0, demands=[0, 0, 0, 0], skill_requirements=None)], successors=[3, 4], delays=None, optional=True, selection_groups=[[3], [4]], name='')"
      ]
     },
     "execution_count": 16,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "activity = instance.activities[1]\n",
    "activity"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "a955cdd4-fb27-491f-8ebd-d26737c9c9d7",
   "metadata": {},
   "source": [
    "This activity has two selection groups, one with activity 3, and the other with activity 4.\n",
    "If this activity is scheduled, then both activity 3 and activity must be scheduled."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "01d7ae4f-58c3-445b-899c-2919a0fd3a79",
   "metadata": {},
   "source": [
    "### ASLIB\n",
    "The \"ASLIB\" format is the format used for RCPSP with alternative subgraph (RCPSP-AS) instances at https://www.projectmanagement.ugent.be/research/project_scheduling/rcpspas.\n",
    "\n",
    "Like the RCPSP-PS, the RCPSP-AS also has optional tasks and selection groups, but they use slightly different concepts (branches and subgraphs). \n",
    "\n",
    "**Important**: RCPSP-AS instances from the ASLIB instance set contain multiple file parts (a, b, c).\n",
    "Our library parses _merged part (a) and (b)_ files, meaning that you have to manually concatenate files first.\n",
    "See the instance file for details."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 17,
   "id": "e9a53c91-5102-4a7a-8768-24fa645370c2",
   "metadata": {},
   "outputs": [],
   "source": [
    "instance = parse(\"data/aslib0_0.rcp\", instance_format=\"aslib\")"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 18,
   "id": "26e640fe-bac2-41dc-8761-f645d144dc74",
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "(5, 122)"
      ]
     },
     "execution_count": 18,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "(instance.num_resources, instance.num_activities)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 19,
   "id": "21d245eb-c3b4-4717-9597-f1850e3f9689",
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "Activity(modes=[Mode(duration=0, demands=[0, 0, 0, 0, 0], skill_requirements=None)], successors=[1, 13, 25, 37, 49], delays=None, optional=False, selection_groups=[[1, 13, 25, 37, 49]], name='')"
      ]
     },
     "execution_count": 19,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "activity = instance.activities[0]  # source\n",
    "activity"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 20,
   "id": "889d69b0-b492-4423-9d9d-64bac9875141",
   "metadata": {
    "scrolled": true
   },
   "outputs": [
    {
     "data": {
      "text/plain": [
       "Activity(modes=[Mode(duration=0, demands=[0, 0, 0, 0, 0], skill_requirements=None)], successors=[2, 3, 4, 5, 6, 7], delays=None, optional=True, selection_groups=[[2], [3], [4], [5], [6], [7]], name='')"
      ]
     },
     "execution_count": 20,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "activity = instance.activities[1]\n",
    "activity"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "8a77d38a-baec-4958-859f-99c38530bc6c",
   "metadata": {},
   "source": [
    "### MSLIB\n",
    "\n",
    "The \"MSLIB\" format is the format used for multi-skilled RCPSP (MSRCPSP) instances at https://www.projectmanagement.ugent.be/research/project_scheduling/MSRCPSP."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 21,
   "id": "693adb89-75d7-4524-837a-4768716aeddb",
   "metadata": {},
   "outputs": [],
   "source": [
    "instance = parse(\"data/MSLIB_Set1_1.msrcp\", instance_format=\"mslib\")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "7a1cac8b-1c49-497a-96c0-9ffcb68c2b19",
   "metadata": {},
   "source": [
    "The MSRCPSP extends the RCPSP by introducing _skills_. Each instance has a set of skills:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 22,
   "id": "36dfe325-98f4-4107-a6f5-89fe55563e7a",
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "[0, 1, 2, 3]"
      ]
     },
     "execution_count": 22,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "instance.skills"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "bfe79467-35ab-4464-a2e1-4f2591f4fcde",
   "metadata": {},
   "source": [
    "Resources may or may not have the corresponding skill:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 23,
   "id": "92c5c8ef-6ace-484a-a601-e52cdd88714f",
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "Resource(capacity=1, renewable=True, skills=[True, True, True, True])"
      ]
     },
     "execution_count": 23,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "instance.resources[0]"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "db266407-2ea5-4250-8886-678fca6c2ac6",
   "metadata": {},
   "source": [
    "Resources all have a capacity of one, because each resource can be only used once for a given activity."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "a5fc75fd-3e31-44ae-9c8e-62029efabce8",
   "metadata": {},
   "source": [
    "Activity modes now require a number of skills:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 24,
   "id": "16e83b04-36a8-465a-aae4-3664e03f613c",
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "Mode(duration=7, demands=[0, 0, 0, 0], skill_requirements=[0, 3, 0, 0])"
      ]
     },
     "execution_count": 24,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "instance.activities[1].modes[0]"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "8e2be392-a04a-42e6-ad31-71814b637296",
   "metadata": {},
   "source": [
    "Note that the demands are all zero. Instead, demand is binary and determined by whether a resource or not."
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3 (ipykernel)",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3.10.10"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 5
}