AgentsAndEvents.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "source": "[![View in Deepnote](https://deepnote.com/static/buttons/view-in-deepnote-white.svg)](https://deepnote.com/viewer/github/katetruman/MultiAgentEC/blob/master/AgentsAndEvents.ipynb)",
   "metadata": {
    "cell_id": "390ea596-38f8-4693-89c9-76e51459b9d3",
    "tags": [],
    "deepnote_cell_type": "markdown"
   }
  },
  {
   "cell_type": "markdown",
   "source": "# Multi-hospital Organ Transplants ",
   "metadata": {
    "tags": [],
    "is_collapsed": false,
    "deepnote_app_coordinates": {
     "x": 0,
     "y": null,
     "w": 12,
     "h": 5
    },
    "cell_id": "9a13a168-06bd-4362-8727-28bcea995904",
    "deepnote_cell_height": 82,
    "deepnote_cell_type": "text-cell-h1"
   }
  },
  {
   "cell_type": "markdown",
   "source": "This organ donation scenario contains a monitoring system and individual hospitals as agents, and models some expectations these agents may have, and whether the expectations are fulfilled or violated. \n\nIn this scenario, patients in need of an organ donation can be added to a wait list. When a donor becomes available, the waiting list should be checked for matches with potential recipients. If a match / matches are found, an organ transplant should take place. \n\nThis notebook describes the actions that agents can make. We then explore different expectation rules related to these actions in other notebooks. Please refer to **Expectations.ipynb** for general notes on expectations, and the **ExpectationExamples** folder for specific examples.",
   "metadata": {
    "tags": [],
    "deepnote_app_coordinates": {
     "x": 0,
     "y": 174,
     "w": 12,
     "h": 5
    },
    "cell_id": "00001-80957c97-c6c0-44a8-83b2-46840724e5ce",
    "deepnote_cell_height": 190,
    "deepnote_cell_type": "markdown"
   }
  },
  {
   "cell_type": "markdown",
   "source": "## Scenario Agents and Events",
   "metadata": {
    "tags": [],
    "is_collapsed": false,
    "deepnote_app_coordinates": {
     "x": 0,
     "y": 0,
     "w": 12,
     "h": 5
    },
    "cell_id": "00002-77eec006-7f6f-4d29-a88d-29950167ce76",
    "deepnote_cell_height": 70,
    "deepnote_cell_type": "text-cell-h2"
   }
  },
  {
   "cell_type": "markdown",
   "source": "In the organ donation scenario and other product tracking scenarios, we have resources and orders which require resources to complete. In the organ donation scenario, our \"orders\" are the patients on the organ waiting lists, and our \"resources\" are the organs which are offered for donation. In this scenario, it is the resources that are the limiting factor - we have to wait for a donation offer to be made in order to match a donor and a recipient / recipients. This is contrast to many other scenarios, where we can stockpile our resources but have to wait for an order to be made to know which resources to allocate it at the time. \n\nAn example of such a scenario would be a business which makes furniture. A certain amount of furniture can be made in advance of orders, so we acquire resources and must wait for a customer order in order to move the stock. In the furniture business scenario, we may also be able to accept orders for furniture that has not yet been made. Thus, such a scenario requires lists of both existing resources and orders. In the organ donation scenario, we create a list of organ \"orders\", but do not need to store organ \"resources\" for future orders due to the quick turn around required between a donor's death and their organs being transplanted.",
   "metadata": {
    "cell_id": "bc617256-68e4-41c8-b13a-0463ad88c484",
    "tags": [],
    "deepnote_app_coordinates": {
     "x": 0,
     "y": 0,
     "w": 12,
     "h": 5
    },
    "deepnote_cell_height": 220,
    "deepnote_cell_type": "markdown"
   }
  },
  {
   "cell_type": "markdown",
   "source": "The following diagram shows the main events needed to facilitate resource to order matching in a generalised scenario. We will use the furniture store example to explain the meaning of the events. The monitoring system can be thought of as the main agent for a business or organisation.\n- The **monitoring system** receives **resource add requests** from a **resource provider** agent. In the case of a furniture store, this could be the store receiving notifications about wood suitable for furnitute making which is available from a particular mill.\n- The monitoring system is able to either **accept** or **reject** the **resource add request**. If a request is accepted, the resource list detailing currently available resources will be updated.\n- **Customers** can make **product orders** which the monitoring system can **match** with available resources, **reject**, or add to a **waiting list**.\n- When a new or waiting order is matched with available resources, the monitoring system sends a match notification to the relevant agents. This could include the **resource** provider, the **customer** and any **supporting agents**. The monitoring system then waits for each of the notified agents to **accept the match**. While there may be certain scenarios where the customer shouldn't need to confirm their order, in this case we assume that they do need to. In the furniture store example, a **supporting agent** could be the courier service for transporting the furniture, and they have to confirm they have the capability to accept a large order before the monitoring system fully processes it.\n- Once all agents who have been notified about the match have accepted it (if required), the monitoring system **confirms the match**. After this point, any actions that need to occur for the customer to get their order are undertaken.\n\nIf the image below is not displaying properly, you can view it [here](https://github.com/katetruman/MultiAgentEC/blob/master/ActorImages/general.png).\n<img src=\"ActorImages/general.png\" width=\"800\">\n",
   "metadata": {
    "cell_id": "07ddbe7e-1c84-458d-b0ec-30b867b28640",
    "tags": [],
    "deepnote_app_coordinates": {
     "x": 0,
     "y": 0,
     "w": 12,
     "h": 5
    },
    "deepnote_cell_height": 960,
    "deepnote_cell_type": "markdown"
   }
  },
  {
   "cell_type": "markdown",
   "source": "We now consider the organ transplant specific scenario, in which we have no need for a resource waiting list.\n- A hospital with a patient in need of an organ sends a **waiting list add request**. The **monitoring system** can accept or reject it.\n- A hospital with a patient ready to donate organs sends a **donor offer** to the monitoring system. The monitoring system either matches the donor offer to one or more patients on the waiting list, or declares that no match could be found. If no match is found, the monitoring system sends a notification to the hospital which made the donation offer.\n- If a match is found, the monitoring system notifies the **recipient's hospital**, the **donor's hospital** and the **transplant location**.\n- Once all three agents have accepted the match, the monitoring system sends a **match confirmation** message to the agents, and the transplant then takes place.",
   "metadata": {
    "cell_id": "2efe3c75-b472-475b-878a-6d84920a8c64",
    "tags": [],
    "deepnote_app_coordinates": {
     "x": 0,
     "y": 0,
     "w": 12,
     "h": 5
    },
    "deepnote_cell_height": 199,
    "deepnote_cell_type": "markdown"
   }
  },
  {
   "cell_type": "markdown",
   "source": "If the image below is not displaying properly, you can view it [here](https://github.com/katetruman/MultiAgentEC/blob/master/ActorImages/organ.png).\n<img src=\"ActorImages/organ.png\" width=\"800\">",
   "metadata": {
    "cell_id": "c2d9c8aa-401c-4c0a-b639-bda3e88d2734",
    "tags": [],
    "deepnote_app_coordinates": {
     "x": 0,
     "y": 0,
     "w": 12,
     "h": 5
    },
    "deepnote_cell_height": 870,
    "deepnote_cell_type": "markdown"
   }
  },
  {
   "cell_type": "markdown",
   "source": "### Set up",
   "metadata": {
    "tags": [],
    "is_collapsed": false,
    "deepnote_app_coordinates": {
     "x": 0,
     "y": 6,
     "w": 12,
     "h": 5
    },
    "cell_id": "00003-b7c7e3e6-8130-4e28-a854-e9d5864b9e97",
    "deepnote_cell_height": 62,
    "deepnote_cell_type": "text-cell-h3"
   }
  },
  {
   "cell_type": "markdown",
   "source": "We load additional predicates from the `dec:notation.pl` file.",
   "metadata": {
    "tags": [],
    "deepnote_app_coordinates": {
     "x": 0,
     "y": 0,
     "w": 12,
     "h": 5
    },
    "cell_id": "00004-becd3284-2eb2-4035-9419-60e9533accaa",
    "deepnote_cell_height": 52,
    "deepnote_cell_type": "markdown"
   }
  },
  {
   "cell_type": "code",
   "metadata": {
    "tags": [],
    "deepnote_to_be_reexecuted": false,
    "source_hash": "9a0bdbe",
    "execution_start": 1645502020892,
    "execution_millis": 61,
    "deepnote_app_coordinates": {
     "x": 0,
     "y": 12,
     "w": 12,
     "h": 5
    },
    "cell_id": "00005-e15cff23-cdb2-4d31-bdc1-16af08606d05",
    "deepnote_cell_height": 208,
    "deepnote_cell_type": "code"
   },
   "source": "?- cd('~/work'), ['dec:notation'].\n?- initialiseDEC.\n?- retractall(happensAtNarrative(_,_)).",
   "execution_count": 1,
   "outputs": [
    {
     "name": "stdout",
     "text": "true.\nfalse.\ntrue.",
     "output_type": "stream"
    }
   ]
  },
  {
   "cell_type": "markdown",
   "source": "### Agents",
   "metadata": {
    "tags": [],
    "is_collapsed": false,
    "deepnote_app_coordinates": {
     "x": 0,
     "y": 0,
     "w": 12,
     "h": 5
    },
    "cell_id": "00006-2dfde0e0-b32b-4e83-9eea-d7bdab41941c",
    "deepnote_cell_height": 62,
    "deepnote_cell_type": "text-cell-h3"
   }
  },
  {
   "cell_type": "markdown",
   "source": "**monSys** (Monitoring System) is our main agent. It facilitates organ transplants by using information about potential recipients and donors to match them. **monSys** receives messages from hospitals (other agents), which detail requests to add patients to organ waiting lists, offer available organs for donation, and respond to previous messages. Both **monSys** and the individual hospitals have expectations about various steps of the organ transplant process.\n\nNote that the first argument of `initiates`, `terminates` and `happensAtNarrative` clauses use the `Agent:Event` format, while the argument of `initially` clauses uses the `Agent:Fluent` format. \n\nThe `agent/1` fluent is used to declare which agents are known to **monSys**. For example, the following code means that from time period zero, **Otago** hospital is recognised as an agent by **monSys**.\n- `initially(monSys:agent(\"Otago\")).`\n\nWe declare four agents as being recognised by **monSys** at the start of our scenario. They are Otago, Christchurch, Wellington and Auckland hospitals.",
   "metadata": {
    "tags": [],
    "deepnote_app_coordinates": {
     "x": 0,
     "y": 18,
     "w": 12,
     "h": 5
    },
    "cell_id": "00007-9802ae04-1da0-4d14-9ae8-8d1f6f10de63",
    "deepnote_cell_height": 284,
    "deepnote_cell_type": "markdown"
   }
  },
  {
   "cell_type": "code",
   "metadata": {
    "tags": [],
    "deepnote_to_be_reexecuted": false,
    "source_hash": "60d33e10",
    "execution_start": 1645502020956,
    "execution_millis": 47,
    "deepnote_app_coordinates": {
     "x": 0,
     "y": 24,
     "w": 12,
     "h": 5
    },
    "cell_id": "00008-9ef2e04b-ed02-4081-b588-5374f01bd304",
    "deepnote_cell_height": 153,
    "deepnote_cell_type": "code"
   },
   "source": "% File: agents.pl\ninitially(monSys:agent(\"Otago\")).\ninitially(monSys:agent(\"Christchurch\")).\ninitially(monSys:agent(\"Wellington\")).\ninitially(monSys:agent(\"Auckland\")).",
   "execution_count": 2,
   "outputs": [
    {
     "name": "stdout",
     "text": "",
     "output_type": "stream"
    }
   ]
  },
  {
   "cell_type": "markdown",
   "source": "### Messaging",
   "metadata": {
    "tags": [],
    "is_collapsed": false,
    "deepnote_app_coordinates": {
     "x": 0,
     "y": 0,
     "w": 12,
     "h": 5
    },
    "cell_id": "00009-efb596c1-6520-4f71-b48b-81ab31574cd5",
    "deepnote_cell_height": 62,
    "deepnote_cell_type": "text-cell-h3"
   }
  },
  {
   "cell_type": "markdown",
   "source": "In order to show the behaviour of multiple agents, we allow **monSys** to send messages to and receive messages from individual agents. For example, Otago hospital could send a message to **monSys**, asking for a patient to be added to the organ waiting list. After **monSys** has successfully added the patient to the waiting list, **monSys** can send a message which confirms the addition. We wish to model our agents as having distinct events and fluents, and thus messages must be sent in order to share information. A message is received one time period after it is sent. We can use the `causes/3` predicate to declare that one event causes another to occur at the next time period. The `causes`, `send` and `receives` fluents would be better placed in **dec:notation.pl**, but are shown here for clarity. The sending and receiving capability could be used by a wide range of agents, and is not restricted to the organ transplant scenario.",
   "metadata": {
    "tags": [],
    "deepnote_app_coordinates": {
     "x": 0,
     "y": 30,
     "w": 12,
     "h": 5
    },
    "cell_id": "00010-634d82b3-3830-4079-80a0-744ac4b47bb9",
    "deepnote_cell_height": 140,
    "deepnote_cell_type": "markdown"
   }
  },
  {
   "cell_type": "code",
   "metadata": {
    "tags": [],
    "deepnote_app_coordinates": {
     "x": 0,
     "y": 36,
     "w": 12,
     "h": 5
    },
    "deepnote_to_be_reexecuted": false,
    "source_hash": "e3f932a9",
    "execution_start": 1645502021001,
    "execution_millis": 3,
    "cell_id": "00011-f9d2e7ba-cc80-4104-8af4-8a4c17f175e1",
    "deepnote_cell_height": 261,
    "deepnote_cell_type": "code"
   },
   "source": "% File: insertDec.pl\n:- discontiguous causes/3.\n:- multifile causes/3.\n% Provide support for \"follow-on\" events using causes/3.\nhappensAt(Hospital2, Event2, T1):- \n    causes(Hospital1:Event1, Hospital2:Event2, T), \n    happensAt(Hospital1, Event1, T), T1 is T + 1.\n\n\n% Recipient agent receives request one time period after sender agent sends message.\ncauses(Hospital:send(Recipient, Message), Recipient:receive(Hospital, Message), _).",
   "execution_count": 3,
   "outputs": [
    {
     "name": "stdout",
     "text": "",
     "output_type": "stream"
    }
   ]
  },
  {
   "cell_type": "markdown",
   "source": "### Organ waiting list",
   "metadata": {
    "tags": [],
    "is_collapsed": false,
    "deepnote_app_coordinates": {
     "x": 0,
     "y": 0,
     "w": 12,
     "h": 5
    },
    "cell_id": "00012-7b0e5a84-4455-46b6-bc42-b4fd834e0533",
    "deepnote_cell_height": 62,
    "deepnote_cell_type": "text-cell-h3"
   }
  },
  {
   "cell_type": "markdown",
   "source": "If a hospital has a patient that they want to be added to the organ waiting list, they send a `waitAddReq` (waiting list add request) message to **monSys**. This message includes the patient's ID, the organs that they need, and a list of further patient details, which could include their sex assigned at birth, ethnicity, date of birth, health conditions and any other notes. \n\nThe general structure of the message is as follows: \n- `happensAtNarrative(Hospital:send(monSys, waitAddReq(ID, Organs, Details)), Time)`. \n\nFor example, the following event indicates that at time period zero, Otago sends a waiting list add request to **monSys** requesting that patient 101 be added to the waiting list for a liver and kidney transplant. The details provided for Patient 101 are that they are female, and their date of birth is the 1st of January 2000.\n- `happensAtNarrative(\"Otago\":send(monSys, waitAddReq(101, [\"liver\", \"kidney], [sex:\"F\", dob:\"01/01/2000\"])), 0).` \n\nThis type of message could be easily adjusted for a different scenario, with the second argument of a waiting list add request referring to furniture items, medical supplies or lifestock instead of organs.",
   "metadata": {
    "tags": [],
    "deepnote_app_coordinates": {
     "x": 0,
     "y": 54,
     "w": 12,
     "h": 5
    },
    "cell_id": "00013-69471889-3215-48c7-863c-8425c3e38ba2",
    "deepnote_cell_height": 298,
    "deepnote_cell_type": "markdown"
   }
  },
  {
   "cell_type": "markdown",
   "source": "In order to reduce the number of manual event entries for modelling this scenario, the monitoring system performs several actions automatically. For instance, **monSys** automatically accepts requests to add a patient to the waiting list if the add request does not cause any expectation rule violations. The hospital is notified that a patient has been successfully added by a `waitAccept` message. If any expectation rule violations occur, the request is denied and the hospital is notified by a `waitReject` message. Again, this behaviour could apply to a range of other situations. \n",
   "metadata": {
    "tags": [],
    "deepnote_app_coordinates": {
     "x": 0,
     "y": 66,
     "w": 12,
     "h": 5
    },
    "cell_id": "00015-e4c08e19-28d7-4db7-8213-a4e5751e25ed",
    "deepnote_cell_height": 118,
    "deepnote_cell_type": "markdown"
   }
  },
  {
   "cell_type": "code",
   "metadata": {
    "tags": [],
    "deepnote_app_coordinates": {
     "x": 0,
     "y": 114,
     "w": 12,
     "h": 5
    },
    "deepnote_to_be_reexecuted": false,
    "source_hash": "299324c0",
    "execution_start": 1645502021028,
    "execution_millis": 4,
    "cell_id": "00016-242169ea-db02-41fa-80fe-f1b4d4008112",
    "deepnote_cell_height": 297,
    "deepnote_cell_type": "code"
   },
   "source": "% File: waitList.pl\n% The monitoring system automatically accepts wait list requests if there are no violations.\ninitiates(monSys:receive(Hospital, waitAddReq(ID, Organs, Details)), waiting(ID, Hospital, Organs, Details, T),T):- \n\\+ happensAt(monSys, viol(happ(receive(Hospital, waitAddReq(ID, Organs, Details))),_,_,_),T).\n\n% When a wait list request is accepted or rejected, the hospital is notified one time period afterwards.\ncauses(monSys:viol(happ(receive(Hospital, waitAddReq(ID, _, _))), _, _, _, _, Reason), \nmonSys:send(Hospital, waitReject(ID, Reason)), _).\n\nhappensAt(monSys, send(Hospital, waitAccept(ID)), T1):- \n    happensAt(monSys, receive(Hospital, waitAddReq(ID, _, _)), T), \n    \\+ happensAt(monSys, viol(happ(receive(Hospital, waitAddReq(ID, _, _))), _, _, _, _, _),T), \n    T1 is T + 1.",
   "execution_count": 4,
   "outputs": [
    {
     "name": "stdout",
     "text": "",
     "output_type": "stream"
    }
   ]
  },
  {
   "cell_type": "markdown",
   "source": "A hospital can also request that a patient be removed from the waiting list, by sending a `waitDelReq` (waiting list deletion request) message to **monSys**. This message includes the patientID and a reason for their removal from the list.\nFor example, the following event indicates that at time two, Otago sends a waiting list deletion request to **monSys** requesting that patient 101 be deleted from the waiting list, due to the death of the patient.\n- `happensAtNarrative(\"Otago\":send(monSys, waitDelReq(101, \"Patient Death\")), 2).`\n\nA patient can also be removed from the waiting list or the list of organs that they are waiting for can be modified, upon a successful organ transplant taking place.",
   "metadata": {
    "tags": [],
    "deepnote_app_coordinates": {
     "x": 0,
     "y": 72,
     "w": 12,
     "h": 5
    },
    "cell_id": "00017-66cbcd6f-9691-47e9-8fd4-8461848e49d5",
    "deepnote_cell_height": 168,
    "deepnote_cell_type": "markdown"
   }
  },
  {
   "cell_type": "code",
   "metadata": {
    "tags": [],
    "deepnote_app_coordinates": {
     "x": 0,
     "y": 78,
     "w": 12,
     "h": 5
    },
    "deepnote_to_be_reexecuted": false,
    "source_hash": "955763c3",
    "execution_start": 1645502021029,
    "execution_millis": 3,
    "cell_id": "00018-f8c5e078-2be6-4676-9b70-2196baac838a",
    "deepnote_cell_height": 351,
    "deepnote_cell_type": "code"
   },
   "source": "% File: waitListDeletions.pl\n\n% If a hospital asks that a patient be removed from the waiting list, their \"waiting\" status is terminated.\nterminates(monSys:receive(Hospital, waitDelReq(ID,_)), waiting(ID,Hospital,_,_,_),_).\n\n% If the waiting patient receives organs they needed, remove them from the waiting list.\nterminates(monSys:receive(Location, transplantOutcome(MatchID, success)), \nwaiting(RecipientID, RecipientHospital, _, _, _), T):- \n    holdsAt(monSys, matched(MatchID, _, _, RecipientHospital, RecipientID, Location, _, _), T).\n\n% Create a new entry for the patient if they are still waiting on any organs.\ninitiates(monSys:receive(Location, transplantOutcome(MatchID, success)), waiting(RecipientID, \nRecipientHospital,NewOrgans, Details, T1), T):- \n    holdsAt(monSys, matched(MatchID, _, _, RecipientHospital, RecipientID, Location, ReceiveOrgans, _), T),\n    holdsAt(monSys, waiting(RecipientID, RecipientHospital, OldOrgans, Details, T1),T), \n    subtract(OldOrgans, ReceiveOrgans, NewOrgans), NewOrgans \\= [].",
   "execution_count": 5,
   "outputs": [
    {
     "name": "stdout",
     "text": "",
     "output_type": "stream"
    }
   ]
  },
  {
   "cell_type": "markdown",
   "source": "While updates could be used to add details of new medical tests performed on a patient, or correct past information entered in error, for simplicity, we declare the behaviour of wait list updates to simply overwrite the previous organ and detail information in a patient's waiting list record.",
   "metadata": {
    "cell_id": "55cecd79-bf19-4c02-a885-4cfabbfba6e5",
    "tags": [],
    "deepnote_cell_type": "markdown"
   }
  },
  {
   "cell_type": "code",
   "source": "% File waitUpdate.pl\nterminates(monSys:receive(Hospital, waitUpdate(ID, _, _)), waiting(ID, Hospital, _, _, T1), T):- T1 < T.\ninitiates(monSys:receive(Hospital, waitUpdate(ID, Organs, Details)), \nwaiting(ID, Hospital, Organs, Details, T1), T):- holdsAt(monSys, waiting(ID, Hospital, _, _, T1),T).",
   "metadata": {
    "cell_id": "8bd758ab-898e-4bbc-8b8e-34f1236a1c9e",
    "tags": [],
    "deepnote_to_be_reexecuted": false,
    "source_hash": "f59c907e",
    "execution_start": 1645502021030,
    "execution_millis": 9,
    "deepnote_cell_type": "code"
   },
   "outputs": [
    {
     "name": "stdout",
     "text": "",
     "output_type": "stream"
    }
   ],
   "execution_count": 6
  },
  {
   "cell_type": "markdown",
   "source": "### Donor offers",
   "metadata": {
    "tags": [],
    "is_collapsed": false,
    "deepnote_app_coordinates": {
     "x": 0,
     "y": 0,
     "w": 12,
     "h": 5
    },
    "cell_id": "00019-cf4dd7ca-fb7c-4b59-9363-aab95d2fe7ad",
    "deepnote_cell_height": 62,
    "deepnote_cell_type": "text-cell-h3"
   }
  },
  {
   "cell_type": "markdown",
   "source": "A hospital can make a donation offer when a patient becomes eligible for donation by sending a `donorOffer` message to **monSys**. (The eligibility criteria are not covered in this notebook, but in order for a patient to become eligible, brain death or circulatory death must have occurred.) \nThe general structure of a `donorOffer` message is:\n- `happensAtNarrative(Hospital:send(monSys, donorOffer(PatID, Organs, Details)), Time)`\nFor example, the following event indicates that at time period two, Wellington sends a donation offer message to **monSys** offering organs for donation from patient 201. The eligible organs are the heart, kidney, liver, lungs and pancreas, and the patient is a Māori male who has a date of birth of 10th of November, 1978.\n- `happensAtNarrative(\"Wellington\":send(monSys, donorOffer(201, [heart, kidney, liver, lungs, pancreas], [sex:\"M\", ethnicity:[\"Māori\"], dob:\"10/11/1978\"])),2).`",
   "metadata": {
    "tags": [],
    "deepnote_app_coordinates": {
     "x": 0,
     "y": 84,
     "w": 12,
     "h": 5
    },
    "cell_id": "00020-f7cbe987-a7e8-4e1d-94ad-6c4f7698dfb2",
    "deepnote_cell_height": 218,
    "deepnote_cell_type": "markdown"
   }
  },
  {
   "cell_type": "markdown",
   "source": "When **monSys** receives a donorOffer, it initiates the **donorOffered\\4** fluent.",
   "metadata": {
    "cell_id": "87200d51-8af7-41f3-9eb0-87062d589c81",
    "tags": [],
    "deepnote_cell_height": 52,
    "deepnote_cell_type": "markdown"
   }
  },
  {
   "cell_type": "code",
   "metadata": {
    "cell_id": "1ed14c67-1535-4de8-97ee-42ec2c9cf5c9",
    "tags": [],
    "deepnote_to_be_reexecuted": false,
    "source_hash": "a945b80c",
    "execution_start": 1645502021040,
    "execution_millis": 11,
    "deepnote_cell_height": 117,
    "deepnote_cell_type": "code"
   },
   "source": "% File: donorOffered.pl\ninitiates(monSys:receive(Hospital, donorOffer(PatID, Organs, Details)), \ndonorOffered(Hospital, PatID, Organs, Details), _).",
   "execution_count": 7,
   "outputs": [
    {
     "name": "stdout",
     "text": "",
     "output_type": "stream"
    }
   ]
  },
  {
   "cell_type": "markdown",
   "source": "### Matching donors and recipients",
   "metadata": {
    "tags": [],
    "is_collapsed": false,
    "deepnote_app_coordinates": {
     "x": 0,
     "y": 0,
     "w": 12,
     "h": 5
    },
    "cell_id": "00022-343265dc-4f8c-4515-bb89-e430dfac5189",
    "deepnote_cell_height": 62,
    "deepnote_cell_type": "text-cell-h3"
   }
  },
  {
   "cell_type": "markdown",
   "source": "We treat **match** events which match a donor with a potential recipient as being manual events - i.e. these are not automatically created by **monSys**, although **monSys** may have expectations about match events. Once a donor offer has been received by **monSys**, if the **noMatch** event occurs, it means that **monSys** did not make a suitable match between the offered donor and a patient on the waiting list. The **noMatch** event contains the ID of the patient from the donation offer, and a reason no match was made. The **noMatch** event causes an **offerRejected** message to be sent to the hospital which made the offer. The rejection message also contains the patient ID and reason for the rejection.",
   "metadata": {
    "tags": [],
    "deepnote_app_coordinates": {
     "x": 0,
     "y": 0,
     "w": 12,
     "h": 5
    },
    "cell_id": "00023-6da0750a-6d55-4c45-8aaf-3c2b7ae502e5",
    "deepnote_cell_height": 118,
    "deepnote_cell_type": "markdown"
   }
  },
  {
   "cell_type": "code",
   "metadata": {
    "tags": [],
    "deepnote_app_coordinates": {
     "x": 0,
     "y": 0,
     "w": 12,
     "h": 5
    },
    "deepnote_to_be_reexecuted": false,
    "source_hash": "8b105f91",
    "execution_start": 1645502021089,
    "execution_millis": 3,
    "cell_id": "00024-ac26a34c-42f2-4566-a142-884cb2c5b85c",
    "deepnote_cell_height": 99,
    "deepnote_cell_type": "code"
   },
   "source": "% File: donationRefusal.pl\ncauses(monSys:noMatch(Hospital, ID, Reason), monSys:send(Hospital, offerRejected(ID, Reason)), _).",
   "execution_count": 8,
   "outputs": [
    {
     "name": "stdout",
     "text": "",
     "output_type": "stream"
    }
   ]
  },
  {
   "cell_type": "markdown",
   "source": "Match events occur for **monSys** when a match is made between a donation offer and a patient on the waiting list. Note that as donor may provide multiple organs, multiple matches may occur from one donation offer. The match includes the donor and the recipient's ID and hospitals, the location allocated to perform the transplant, the organs to be transplanted and any notes which these hospitals should be aware of. Note that the donor's hospital, the recipient's hospital and the transplant location must not all be unique - for instance, the transplant may take place at the recipient's local hospital. If a hospital has more than one role in a match, it will receive communications from **monSys** for each role it undetakes.\n\nThe general structure of a match event is as follows:\n- `happensAtNarrative(monSys:match(MatchID, DonorHospital, DonorID, RecipientHospital, RecipientID, Location, Organs, Notes), Time)`\nFor example, the following event indicates that at time period four, the monitoring system performs match 401 between the donation offer for patient 201 from Wellington to the recipient 102 from Otago. The transplant is to take place at Auckland, and the only organ being transplanted is the heart. The transplant notes state that the donor is hepatitis C positive.\n- `happensAtNarrative(monSys:match(401, \"Wellington\", 201, \"Otago\", 102, \"Auckland\", [heart], [donorCondition:\"HepC\"]),4).`",
   "metadata": {
    "tags": [],
    "deepnote_app_coordinates": {
     "x": 0,
     "y": 96,
     "w": 12,
     "h": 5
    },
    "cell_id": "00025-77b4dfc5-6b41-4471-bff9-35e95d4f6e14",
    "deepnote_cell_height": 298,
    "deepnote_cell_type": "markdown"
   }
  },
  {
   "cell_type": "markdown",
   "source": "When *monSys* makes a match, it notifies the donor's hospital, the recipient's hospital and the allocated location for the transplant to take place. These hospitals are sent a **recipientFound**, **donorFound** or **locationSelected** message respectively. These events initiate fluents of the same name as the message type. A match event also initiates a **matched** fluent for **monSys**. The fluent has the same arguments as the event.",
   "metadata": {
    "tags": [],
    "deepnote_app_coordinates": {
     "x": 0,
     "y": 0,
     "w": 12,
     "h": 5
    },
    "cell_id": "00027-8530a4dc-1b15-4184-9d4a-42a734f3c724",
    "deepnote_cell_height": 96,
    "deepnote_cell_type": "markdown"
   }
  },
  {
   "cell_type": "code",
   "metadata": {
    "tags": [],
    "deepnote_app_coordinates": {
     "x": 0,
     "y": 132,
     "w": 12,
     "h": 5
    },
    "deepnote_to_be_reexecuted": false,
    "source_hash": "f05f3bf8",
    "execution_start": 1645502021090,
    "execution_millis": 2,
    "cell_id": "00028-e0c3085b-f7c0-4ca2-bc63-b56c18c1c7a8",
    "deepnote_cell_height": 459,
    "deepnote_cell_type": "code"
   },
   "source": "% File: matchNotification.pl\ncauses(monSys:match(MatchID, DonorHospital, DonorID, RecipientHospital, _, Location, Organs, Notes), \nmonSys:send(DonorHospital, recipientFound(MatchID, DonorID, RecipientHospital, Location, Organs, Notes)),\n _).\n\ncauses(monSys:match(MatchID, DonorHospital, _, RecipientHospital, RecipientID, Location, Organs, Notes), \nmonSys:send(RecipientHospital, donorFound(MatchID, RecipientID, DonorHospital, Location, Organs, Notes)),\n _).\n\ncauses(monSys:match(MatchID, DonorHospital, _, RecipientHospital, _, Location, Organs, Notes), \nmonSys:send(Location, locationSelected(MatchID, DonorHospital, RecipientHospital, Organs, Notes)), _).\n\ninitiates(_:receive(monSys, recipientFound(MatchID, DonorID, RecipientHospital, Location, Organs, Notes)), \nrecipientFound(MatchID, DonorID, RecipientHospital, Location, Organs, Notes), _).\ninitiates(_:receive(monSys, donorFound(MatchID, RecipientID, DonorHospital, Location, Organs, Notes)), \ndonorFound(MatchID, RecipientID, DonorHospital, Location, Organs, Notes), _).\ninitiates(_:receive(monSys, locationSelected(MatchID, DonorHospital, RecipientHospital, Organs, Notes)), \nlocationSelected(MatchID, DonorHospital, RecipientHospital, Organs, Notes), _).\n\ninitiates(monSys:match(MatchID, DonorHospital, DonorID, RecipientHospital, RecipientID, Location, \nOrgans, Notes), matched(MatchID, DonorHospital, DonorID, RecipientHospital, RecipientID, Location, \nOrgans, Notes), _).",
   "execution_count": 9,
   "outputs": [
    {
     "name": "stdout",
     "text": "",
     "output_type": "stream"
    }
   ]
  },
  {
   "cell_type": "markdown",
   "source": "A match event initiates the **role/3** fluent which details the role of each hospital involved in the planned transplant. The general structure of the fluent is *role(Hospital, MatchID, Role)*. The three roles are *donor*, *recipient* and *transplant*, where the final name refers to the hospital where the transplant should take place.\n\nFor example, the following fluent represents that Otago is the recipient's hospital for match 401:\n- `role(\"Otago\", 401, recipient)`",
   "metadata": {
    "tags": [],
    "deepnote_app_coordinates": {
     "x": 0,
     "y": 0,
     "w": 12,
     "h": 5
    },
    "cell_id": "00029-5165a7a3-c0dc-4585-858d-85fe305f3a73",
    "deepnote_cell_height": 160,
    "deepnote_cell_type": "markdown"
   }
  },
  {
   "cell_type": "code",
   "metadata": {
    "tags": [],
    "deepnote_app_coordinates": {
     "x": 0,
     "y": 156,
     "w": 12,
     "h": 5
    },
    "deepnote_to_be_reexecuted": false,
    "source_hash": "3f6ed6ea",
    "execution_start": 1645502021090,
    "execution_millis": 4,
    "cell_id": "00030-db0c90f3-fcac-49e8-bb9d-27872cdbdf34",
    "deepnote_cell_height": 153,
    "deepnote_cell_type": "code"
   },
   "source": "% File: matchRoles.pl\ninitiates(monSys:match(MatchID, DonorHospital, _, _, _, _, _, _), role(DonorHospital, MatchID, donor), _).\ninitiates(monSys:match(MatchID, _, _, RecipientHospital, _, _, _, _), role(RecipientHospital, MatchID, \nrecipient), _).\ninitiates(monSys:match(MatchID, _, _, _, _, Location, _, _), role(Location, MatchID, transplant), _).",
   "execution_count": 10,
   "outputs": [
    {
     "name": "stdout",
     "text": "",
     "output_type": "stream"
    }
   ]
  },
  {
   "cell_type": "markdown",
   "source": "Once a hospital has received a `recipientFound`, `donorFound` or `locationSelected` notification, they can send an `acceptMatch` message to accept their role in the proposed transplant. `acceptMatch` events initiate `matchAccepted` fluents. Once `acceptMatch` messages for all three roles have been received, a `confirmationMatch` event automatically takes place for **monSys**. This event takes the match ID as its sole argument, and causes a `confirmedNotification` message to be sent to the hospitals involved. This message signifies that the hospitals should undertake whatever actions are required for the transplant to take place, such as removing the required organs from the donor, transporting the organs and the recipient to the transplant location, and finally undertaking the transplant.",
   "metadata": {
    "tags": [],
    "deepnote_app_coordinates": {
     "x": 0,
     "y": 0,
     "w": 12,
     "h": 5
    },
    "cell_id": "00031-fd23c70f-788e-4fd4-8496-55132c6cb293",
    "deepnote_cell_height": 140,
    "deepnote_cell_type": "markdown"
   }
  },
  {
   "cell_type": "code",
   "metadata": {
    "tags": [],
    "deepnote_app_coordinates": {
     "x": 0,
     "y": 162,
     "w": 12,
     "h": 5
    },
    "deepnote_to_be_reexecuted": false,
    "source_hash": "3ae93118",
    "execution_start": 1645502021126,
    "execution_millis": 4,
    "cell_id": "00032-448d879b-02c4-4f31-b7b1-2e13d030ab45",
    "deepnote_cell_height": 423,
    "deepnote_cell_type": "code"
   },
   "source": "% File: matchConfirmation.pl\ninitiates(monSys:receive(Hospital, acceptMatch(ID)), matchAccepted(Hospital,ID),_).\n\nhappensAt(monSys, confirmationMatch(MatchID),T):- \n    holdsAt(monSys, role(DonorHospital, MatchID, donor), T), \n    holdsAt(monSys, role(RecipientHospital, MatchID, recipient), T), \n    holdsAt(monSys, role(Location, MatchID, transplant), T),\n    happensAt(monSys, receive(Hospital, acceptMatch(MatchID)),T), (Hospital = DonorHospital ; \n    Hospital = RecipientHospital; Hospital = Location),\n    (happensAt(monSys, receive(DonorHospital, acceptMatch(MatchID)),T); \n    holdsAt(monSys, matchAccepted(DonorHospital, MatchID),T)), \n    (happensAt(monSys, receive(RecipientHospital, acceptMatch(MatchID)),T); \n    holdsAt(monSys, matchAccepted(RecipientHospital, MatchID),T)),\n    (happensAt(monSys, receive(Location, acceptMatch(MatchID)),T); \n    holdsAt(monSys, matchAccepted(Location, MatchID),T)), !.\n\ninitiates(monSys:confirmationMatch(MatchID), confirmed(MatchID), _).\n\ncauses(monSys:confirmationMatch(MatchID), monSys:send(Hospital, confirmedNotification(MatchID)), T):- \n    holdsAt(monSys, role(Hospital, MatchID, _),T).",
   "execution_count": 11,
   "outputs": [
    {
     "name": "stdout",
     "text": "",
     "output_type": "stream"
    }
   ]
  },
  {
   "cell_type": "markdown",
   "source": "A `transplant` event should take place at the selected transplant location. The `transplant` event has two arguments - the match ID and the outcome of the transplant (e.g. \"Success\" or \"Failure\"). In reality, the outcome could be much more complicated e.g. the patient is recovering well but needs to be monitored closely. However, we won't go into this level of detail here. A `transplant` event initiates the `transplanted` fluent, and causes `transplantOutcome` messages to be sent to the recipient hospital, the donor hospital and **monSys**.",
   "metadata": {
    "cell_id": "f251774f-a6f5-4787-915c-e439cd636f2d",
    "tags": [],
    "deepnote_cell_height": 96,
    "deepnote_cell_type": "markdown"
   }
  },
  {
   "cell_type": "code",
   "metadata": {
    "cell_id": "c76c4725-3b53-4af3-84b0-a439f47597eb",
    "tags": [],
    "deepnote_to_be_reexecuted": false,
    "source_hash": "759b3ec9",
    "execution_start": 1645502021127,
    "execution_millis": 3,
    "deepnote_cell_height": 153,
    "deepnote_cell_type": "code"
   },
   "source": "% File: transplant.pl\ninitiates(_:transplant(ID, Outcome), transplanted(ID, Outcome), _).\ncauses(Location:transplant(ID, Outcome), Location:send(OtherHospital, transplantOutcome(ID, Outcome)),T):- \n    holdsAt(Location, locationSelected(ID, DonorHospital, RecipientHospital, _, _), T), \n    (OtherHospital = DonorHospital ; OtherHospital = RecipientHospital; OtherHospital = monSys).",
   "execution_count": 12,
   "outputs": [
    {
     "name": "stdout",
     "text": "",
     "output_type": "stream"
    }
   ]
  },
  {
   "cell_type": "markdown",
   "source": "### Statistics requests",
   "metadata": {
    "tags": [],
    "is_collapsed": false,
    "deepnote_app_coordinates": {
     "x": 0,
     "y": 0,
     "w": 12,
     "h": 5
    },
    "cell_id": "00034-9fbe7f3b-1eea-4634-9a73-09cf4e8c8cae",
    "deepnote_cell_height": 62,
    "deepnote_cell_type": "text-cell-h3"
   }
  },
  {
   "cell_type": "markdown",
   "source": "As well as taking part in matching active patients, **monSys** and hospitals may have an interest in viewing statistics on historical data.",
   "metadata": {
    "tags": [],
    "deepnote_app_coordinates": {
     "x": 0,
     "y": 0,
     "w": 12,
     "h": 5
    },
    "cell_id": "00035-3a36365e-bc99-484b-a7d7-64b618f23543",
    "deepnote_cell_height": 52,
    "deepnote_cell_type": "markdown"
   }
  },
  {
   "cell_type": "code",
   "metadata": {
    "tags": [],
    "deepnote_app_coordinates": {
     "x": 0,
     "y": 108,
     "w": 12,
     "h": 5
    },
    "deepnote_to_be_reexecuted": false,
    "source_hash": "b78bd541",
    "execution_start": 1645502021128,
    "execution_millis": 4,
    "cell_id": "00036-ad740d98-e132-4541-8e3b-e28ee5988f7c",
    "deepnote_cell_height": 99,
    "deepnote_cell_type": "code"
   },
   "source": "% File: statRequests.pl\n%happensAtNarrative(\"Wellington\":statReq(percentage, ), 15).\n",
   "execution_count": 13,
   "outputs": [
    {
     "name": "stdout",
     "text": "",
     "output_type": "stream"
    }
   ]
  },
  {
   "cell_type": "markdown",
   "source": "## Saving the scenario",
   "metadata": {
    "tags": [],
    "is_collapsed": false,
    "deepnote_app_coordinates": {
     "x": 0,
     "y": 0,
     "w": 12,
     "h": 5
    },
    "cell_id": "00037-b8e8269b-51d0-4307-b8d4-5224653e637c",
    "deepnote_cell_height": 70,
    "deepnote_cell_type": "text-cell-h2"
   }
  },
  {
   "cell_type": "markdown",
   "source": "So that we can use the events and fluents declared above to support a range of different expectation rules, we save the contents of the above cell blocks into a file we can consult. The kernel automatically saves the contents (excluding comments) of all the cells in a notebook to a file in the **output_files** folder when the notebook is run. Because this will be overwritten next time a notebook is run, we copy the file to our current directory.",
   "metadata": {
    "cell_id": "31a54230-69b2-42bb-979a-8276a931fa07",
    "tags": [],
    "deepnote_app_coordinates": {
     "x": 0,
     "y": 0,
     "w": 12,
     "h": 5
    },
    "deepnote_cell_height": 96,
    "deepnote_cell_type": "markdown"
   }
  },
  {
   "cell_type": "code",
   "metadata": {
    "cell_id": "9a1be6c4-e6ab-47f2-9557-d91f94cfb2f0",
    "tags": [],
    "deepnote_app_coordinates": {
     "x": 0,
     "y": 0,
     "w": 12,
     "h": 5
    },
    "deepnote_to_be_reexecuted": false,
    "source_hash": "fa397ca0",
    "execution_start": 1645502021176,
    "execution_millis": 3,
    "deepnote_cell_height": 117,
    "deepnote_cell_type": "code"
   },
   "source": "% PYTHON\nimport shutil\nshutil.copyfile(\"/work/output_files/allCells.pl\", \"/work/AE.pl\")",
   "execution_count": 14,
   "outputs": [
    {
     "name": "stdout",
     "text": "",
     "output_type": "stream"
    }
   ]
  },
  {
   "cell_type": "markdown",
   "source": "<a style='text-decoration:none;line-height:16px;display:flex;color:#5B5B62;padding:10px;justify-content:end;' href='https://deepnote.com?utm_source=created-in-deepnote-cell&projectId=32f94018-a4da-40ef-8c9f-8983d73811c8' target=\"_blank\">\n<img alt='Created in deepnote.com' style='display:inline;max-height:16px;margin:0px;margin-right:7.5px;' src='data:image/svg+xml;base64,PD94bWwgdmVyc2lvbj0iMS4wIiBlbmNvZGluZz0iVVRGLTgiPz4KPHN2ZyB3aWR0aD0iODBweCIgaGVpZ2h0PSI4MHB4IiB2aWV3Qm94PSIwIDAgODAgODAiIHZlcnNpb249IjEuMSIgeG1sbnM9Imh0dHA6Ly93d3cudzMub3JnLzIwMDAvc3ZnIiB4bWxuczp4bGluaz0iaHR0cDovL3d3dy53My5vcmcvMTk5OS94bGluayI+CiAgICA8IS0tIEdlbmVyYXRvcjogU2tldGNoIDU0LjEgKDc2NDkwKSAtIGh0dHBzOi8vc2tldGNoYXBwLmNvbSAtLT4KICAgIDx0aXRsZT5Hcm91cCAzPC90aXRsZT4KICAgIDxkZXNjPkNyZWF0ZWQgd2l0aCBTa2V0Y2guPC9kZXNjPgogICAgPGcgaWQ9IkxhbmRpbmciIHN0cm9rZT0ibm9uZSIgc3Ryb2tlLXdpZHRoPSIxIiBmaWxsPSJub25lIiBmaWxsLXJ1bGU9ImV2ZW5vZGQiPgogICAgICAgIDxnIGlkPSJBcnRib2FyZCIgdHJhbnNmb3JtPSJ0cmFuc2xhdGUoLTEyMzUuMDAwMDAwLCAtNzkuMDAwMDAwKSI+CiAgICAgICAgICAgIDxnIGlkPSJHcm91cC0zIiB0cmFuc2Zvcm09InRyYW5zbGF0ZSgxMjM1LjAwMDAwMCwgNzkuMDAwMDAwKSI+CiAgICAgICAgICAgICAgICA8cG9seWdvbiBpZD0iUGF0aC0yMCIgZmlsbD0iIzAyNjVCNCIgcG9pbnRzPSIyLjM3NjIzNzYyIDgwIDM4LjA0NzY2NjcgODAgNTcuODIxNzgyMiA3My44MDU3NTkyIDU3LjgyMTc4MjIgMzIuNzU5MjczOSAzOS4xNDAyMjc4IDMxLjY4MzE2ODMiPjwvcG9seWdvbj4KICAgICAgICAgICAgICAgIDxwYXRoIGQ9Ik0zNS4wMDc3MTgsODAgQzQyLjkwNjIwMDcsNzYuNDU0OTM1OCA0Ny41NjQ5MTY3LDcxLjU0MjI2NzEgNDguOTgzODY2LDY1LjI2MTk5MzkgQzUxLjExMjI4OTksNTUuODQxNTg0MiA0MS42NzcxNzk1LDQ5LjIxMjIyODQgMjUuNjIzOTg0Niw0OS4yMTIyMjg0IEMyNS40ODQ5Mjg5LDQ5LjEyNjg0NDggMjkuODI2MTI5Niw0My4yODM4MjQ4IDM4LjY0NzU4NjksMzEuNjgzMTY4MyBMNzIuODcxMjg3MSwzMi41NTQ0MjUgTDY1LjI4MDk3Myw2Ny42NzYzNDIxIEw1MS4xMTIyODk5LDc3LjM3NjE0NCBMMzUuMDA3NzE4LDgwIFoiIGlkPSJQYXRoLTIyIiBmaWxsPSIjMDAyODY4Ij48L3BhdGg+CiAgICAgICAgICAgICAgICA8cGF0aCBkPSJNMCwzNy43MzA0NDA1IEwyNy4xMTQ1MzcsMC4yNTcxMTE0MzYgQzYyLjM3MTUxMjMsLTEuOTkwNzE3MDEgODAsMTAuNTAwMzkyNyA4MCwzNy43MzA0NDA1IEM4MCw2NC45NjA0ODgyIDY0Ljc3NjUwMzgsNzkuMDUwMzQxNCAzNC4zMjk1MTEzLDgwIEM0Ny4wNTUzNDg5LDc3LjU2NzA4MDggNTMuNDE4MjY3Nyw3MC4zMTM2MTAzIDUzLjQxODI2NzcsNTguMjM5NTg4NSBDNTMuNDE4MjY3Nyw0MC4xMjg1NTU3IDM2LjMwMzk1NDQsMzcuNzMwNDQwNSAyNS4yMjc0MTcsMzcuNzMwNDQwNSBDMTcuODQzMDU4NiwzNy43MzA0NDA1IDkuNDMzOTE5NjYsMzcuNzMwNDQwNSAwLDM3LjczMDQ0MDUgWiIgaWQ9IlBhdGgtMTkiIGZpbGw9IiMzNzkzRUYiPjwvcGF0aD4KICAgICAgICAgICAgPC9nPgogICAgICAgIDwvZz4KICAgIDwvZz4KPC9zdmc+' > </img>\nCreated in <span style='font-weight:600;margin-left:4px;'>Deepnote</span></a>",
   "metadata": {
    "tags": [],
    "created_in_deepnote_cell": true,
    "deepnote_cell_type": "markdown"
   }
  }
 ],
 "nbformat": 4,
 "nbformat_minor": 2,
 "metadata": {
  "orig_nbformat": 2,
  "deepnote": {
   "is_reactive": false
  },
  "deepnote_notebook_id": "d98380aa-cb30-4c2f-a718-5d49d16732ec",
  "deepnote_execution_queue": [],
  "deepnote_app_layout": "article"
 }
}