{
 "cells": [
  {
   "cell_type": "markdown",
   "id": "2cf76390",
   "metadata": {},
   "source": [
    "# Perform a substance compliance query"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "1b3e5c63",
   "metadata": {},
   "source": [
    "A substance cmpliance query determines whether one or more substances are compliant with the specified indicators.\n",
    "This example checks several materials for substances included on two watch lists (\"EU REACH - The Candidate List\" and\n",
    "\"The SIN List 2.1\"), specifying substance amounts and thresholds for compliance."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "44823c19",
   "metadata": {},
   "source": [
    "## Connect to Granta MI"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "d28cc826",
   "metadata": {},
   "source": [
    "Import the ``Connection`` class and create the connection. For more information, see the\n",
    "[Getting Started](../0_Getting_started.ipynb) example."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "c5fe1250",
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "from ansys.grantami.bomanalytics import Connection\n",
    "\n",
    "server_url = \"http://my_grantami_server/mi_servicelayer\"\n",
    "cxn = Connection(server_url).with_credentials(\"user_name\", \"password\").connect()"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "57e3efe7",
   "metadata": {},
   "source": [
    "## Define an indicator"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "701298dc",
   "metadata": {},
   "source": [
    "A Compliance query determines compliance against indicators, as opposed to an Impacted Substances query which\n",
    "determines compliance directly against legislations.\n",
    "\n",
    "There are two types of indicator objects (``WatchListIndicator`` and ``RohsIndicator``), and the syntax that\n",
    "follows applies to both object types. The differences in the internal implementation of the two objects are\n",
    "described in the API documentation.\n",
    "\n",
    "Generally speaking, if a substance is impacted by a legislation associated with an indicator and in a quantity\n",
    "above a specified threshold, the substance is non-compliant with that indicator. This non-compliance applies to\n",
    "any other items in the BoM hierarchy that directly or indirectly include that substance."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "ac6aa609",
   "metadata": {},
   "source": [
    "First, create two ``WatchListIndicator`` objects."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "73ca7a82",
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "from ansys.grantami.bomanalytics import indicators\n",
    "\n",
    "svhc = indicators.WatchListIndicator(\n",
    "    name=\"SVHC\",\n",
    "    legislation_ids=[\"Candidate_AnnexXV\"],\n",
    "    default_threshold_percentage=0.1,\n",
    ")\n",
    "sin = indicators.WatchListIndicator(\n",
    "    name=\"SIN\",\n",
    "    legislation_ids=[\"SINList\"]\n",
    ")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "9a6b0be0",
   "metadata": {
    "tags": []
   },
   "source": [
    "## Build and run the query"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "18540a4b",
   "metadata": {},
   "source": [
    "Next, define the query itself. Substances can be referenced by Granta MI record reference, CAS\n",
    "number, EC number, or chemical name.\n",
    "\n",
    "The substance quantity, an optional argument, defaults to 100% if no value is specified."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "a35526cc",
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "from ansys.grantami.bomanalytics import queries\n",
    "\n",
    "sub_query = queries.SubstanceComplianceQuery().with_indicators([svhc, sin])\n",
    "sub_query = sub_query.with_cas_numbers_and_amounts([(\"50-00-0\", 10),\n",
    "                                                    (\"110-00-9\", 25),\n",
    "                                                    (\"302-17-0\", 100),\n",
    "                                                    (\"7440-23-5\", 100)])"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "52dc9878",
   "metadata": {},
   "source": [
    "Finally, run the query. Passing a ``SubstanceComplianceQuery`` object to the ``Connection.run()`` method returns a\n",
    "``SubstanceComplianceQueryResult`` object."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "0576ab8d",
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "sub_result = cxn.run(sub_query)\n",
    "sub_result"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "2a60efe2",
   "metadata": {
    "tags": []
   },
   "source": [
    "The result object contains two properties: ``compliance_by_substance_and_indicator`` and ``compliance_by_indicator``."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "6fd845c7",
   "metadata": {},
   "source": [
    "## Group results by substance"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "3a599bf6",
   "metadata": {
    "tags": []
   },
   "source": [
    "``compliance_by_substance_and_indicator`` contains a list of ``SubstanceWithComplianceResult`` objects that contain\n",
    "the reference to the substance record and the compliance status in the list of indicators. To determine which\n",
    "substances are compliant, loop over each one and compare the indicator to a certain threshold. This\n",
    "example examines the SVHC indicator."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "602da0a8",
   "metadata": {},
   "source": [
    "The possible states of the indicator are available on the ``Indicator.available_flags`` attribute and can be compared\n",
    "using standard Python operators."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "dce7e037",
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "compliant_substances = []\n",
    "non_compliant_substances = []\n",
    "threshold = svhc.available_flags.WatchListAboveThreshold\n",
    "\n",
    "for substance in sub_result.compliance_by_substance_and_indicator:\n",
    "    if (substance.indicators[\"SVHC\"] >= threshold):\n",
    "        non_compliant_substances.append(substance)\n",
    "    else:\n",
    "        compliant_substances.append(substance)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "cd532208",
   "metadata": {},
   "source": [
    "Now print the SVHC and non-SVHC substances."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "b4d4594e",
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "compliant_cas_numbers = [sub.cas_number for sub in compliant_substances]\n",
    "print(f'Non-SVHC substances: {\", \".join(compliant_cas_numbers)}')\n",
    "\n",
    "non_compliant_cas_numbers = [sub.cas_number for sub in non_compliant_substances]\n",
    "print(f'SVHCs: {\", \".join(non_compliant_cas_numbers)}')"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "463a01f5",
   "metadata": {},
   "source": [
    "## Group results by indicator"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "fc148734",
   "metadata": {},
   "source": [
    "Alternatively, using the ``compliance_by_indicator`` property provides a single indicator result\n",
    "that summarizes the results across all substances in the query. This would be useful in a situation\n",
    "where a *concept* material is stored outside of Granta MI but its compliance must be determined.\n",
    "Because you know it contains the substances specified in the preceding query, you can use the\n",
    "``compliance_by_indicator`` property to tell if this concept material is compliant based on\n",
    "the worst result of the individual substances."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "2503be39",
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "if sub_result.compliance_by_indicator[\"SVHC\"] >= threshold:\n",
    "    print(\"One or more substances is an SVHC with a quantity greater than 0.1%\")\n",
    "else:\n",
    "    print(\"No SVHCs are present, or no SVHCs have a quantity less than 0.1%.\")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "e13b2f27",
   "metadata": {},
   "source": [
    "Note that this property does not tell you which substance is responsible for the non-compliance. This would require\n",
    "either performing a more granular analysis as shown earlier or importing the material into Granta MI and running\n",
    "a compliance query on that material record."
   ]
  }
 ],
 "metadata": {
  "jupytext": {
   "formats": "ipynb,py:light"
  },
  "kernelspec": {
   "display_name": "Python 3 (ipykernel)",
   "language": "python",
   "name": "python3"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 5
}