{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Grid Object Examples\n",
    "\n",
    "The `Grid` object represents a grid structure in the `power_grid_model_ds` library. This documentation provides a comprehensive guide on how to use the `Grid` object, including its initialization, adding and removing nodes and branches, activating and deactivating branches, and creating a grid from a text file.\n",
    "\n",
    "## Initialization\n",
    "\n",
    "### Creating an Empty Grid\n",
    "\n",
    "To create an empty grid, use the `Grid.empty()` method. This method initializes an empty grid with default settings.\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from power_grid_model_ds import Grid\n",
    "\n",
    "grid = Grid.empty()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "This creates an empty grid instance. You can verify that the grid is initialized correctly by checking that it contains the fields `arrays` and `graphs`.\n",
    "\n",
    "## Building a Basic Grid\n",
    "\n",
    "In this section, we'll build a basic grid step by step, adding each component separately.\n",
    "\n",
    "### Adding Substations\n",
    "\n",
    "First, we add a substation to the grid. Substations are critical nodes in the grid that typically connect different voltage levels.\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from power_grid_model_ds.arrays import NodeArray\n",
    "from power_grid_model_ds.enums import NodeType\n",
    "\n",
    "substation = NodeArray(id=[101], u_rated=[10_500.0], node_type=[NodeType.SUBSTATION_NODE.value])\n",
    "grid.append(substation, check_max_id=False)\n",
    "substation = NodeArray(id=[102, 103, 104, 105, 106], u_rated=[10_500.0] * 5, node_type=[NodeType.UNSPECIFIED.value] * 5)\n",
    "grid.append(substation, check_max_id=False)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Adding Lines\n",
    "\n",
    "Next, we add lines to the grid. Lines represent the connections between nodes and can be active or inactive.\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from power_grid_model_ds.arrays import LineArray\n",
    "\n",
    "lines = LineArray(\n",
    "    id=[201, 202, 203, 204],\n",
    "    from_status=[1, 1, 0, 1],\n",
    "    to_status=[1, 1, 0, 1],\n",
    "    from_node=[101, 102, 103, 101],\n",
    "    to_node=[102, 103, 104, 105],\n",
    "    i_n=[200.0] * 4,\n",
    "    r1=[0.1] * 4,\n",
    "    x1=[0.03] * 4,\n",
    "    c1=[0.0] * 4,\n",
    "    tan1=[0.0] * 4,\n",
    ")\n",
    "grid.append(lines, check_max_id=False)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "This adds four lines to the grid, connecting different nodes. One of these lines is inactive (`from_status` and `to_status` are 0).\n",
    "\n",
    "### Adding Transformers\n",
    "\n",
    "Transformers are added to connect nodes with different voltage levels.\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from power_grid_model_ds.arrays import TransformerArray\n",
    "\n",
    "trafo = TransformerArray.empty(1)\n",
    "trafo.id = 301\n",
    "trafo.from_status = 1\n",
    "trafo.to_status = 1\n",
    "trafo.from_node = 102\n",
    "trafo.to_node = 106\n",
    "grid.append(trafo, check_max_id=False)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "This adds a transformer between nodes 102 and 106.\n",
    "\n",
    "### Adding Links\n",
    "\n",
    "Links are another type of connection between nodes, often used for specific purposes like bypassing parts of the network.\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from power_grid_model_ds.arrays import LinkArray\n",
    "\n",
    "link = LinkArray.empty(1)\n",
    "link.id = 601\n",
    "link.from_status = 1\n",
    "link.to_status = 1\n",
    "link.from_node = 104\n",
    "link.to_node = 105\n",
    "grid.append(link, check_max_id=False)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "This adds a link between nodes 104 and 105.\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Adding Loads\n",
    "\n",
    "Loads represent consumers of electricity connected to different nodes.\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from power_grid_model_ds.arrays import SymLoadArray\n",
    "\n",
    "loads = SymLoadArray(\n",
    "    id=[401, 402, 403, 404],\n",
    "    node=[102, 103, 104, 105],\n",
    "    type=[1] * 4,\n",
    "    p_specified=[1_000_000.0] * 4,\n",
    "    q_specified=[1_000_000.0] * 4,\n",
    "    status=[1] * 4,\n",
    ")\n",
    "grid.append(loads, check_max_id=False)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "This adds four loads to the grid, each connected to a different node.\n",
    "\n",
    "### Adding a Source\n",
    "\n",
    "Finally, a source is added to provide power to the grid.\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from power_grid_model_ds.arrays import SourceArray\n",
    "\n",
    "source = SourceArray(id=[501], node=[101], status=[1], u_ref=[0.0])\n",
    "grid.append(source, check_max_id=False)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "This adds a power source at node 101.\n",
    "\n",
    "After adding all these components, you should check the IDs to ensure there are no conflicts.\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "grid.check_ids()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Node Operations\n",
    "\n",
    "### Adding a Node\n",
    "\n",
    "To add a node to the grid, use the `append` method. This method adds a new node to the grid's node array.\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from power_grid_model_ds.arrays import NodeArray\n",
    "\n",
    "new_node = NodeArray.zeros(1)\n",
    "grid.append(new_node)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "After adding the node, the total number of nodes in the grid increases by one.\n",
    "\n",
    "### Deleting a Node\n",
    "\n",
    "To delete a node from the grid, use the `delete_node` method. This method removes the specified node from the grid's node array.\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "target_node = grid.node.get(101)\n",
    "grid.delete_node(node=target_node)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Branch Operations\n",
    "\n",
    "### Adding a Line\n",
    "\n",
    "To add a line to the grid, use the `append` method with a `LineArray` object. This method adds a new line between specified nodes.\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from power_grid_model_ds.arrays import LineArray\n",
    "\n",
    "new_line_array = LineArray.zeros(1)\n",
    "new_line_array.from_node = 102\n",
    "new_line_array.to_node = 105\n",
    "grid.append(new_line_array)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "After adding the line, the total number of lines in the grid increases by one, and the line is added to the graph structure.\n",
    "\n",
    "### Deleting a Line\n",
    "\n",
    "To delete a line from the grid, use the `delete_branch` method with the target line array.\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "target_line = grid.line.get(202)\n",
    "grid.delete_branch(branch=target_line)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "After deleting the line, the total number of lines in the grid decreases by one, and the line is removed from the graph structure.\n",
    "\n",
    "### Adding a Link\n",
    "\n",
    "To add a link to the grid, use the `append` method with a `LinkArray` object. This method adds a new link between specified nodes.\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from power_grid_model_ds.arrays import LinkArray\n",
    "\n",
    "new_link_array = LinkArray.zeros(1)\n",
    "new_link_array.from_node = 102\n",
    "new_link_array.to_node = 105\n",
    "grid.append(new_link_array)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "After adding the link, the total number of links in the grid increases by one.\n",
    "\n",
    "### Adding a Transformer\n",
    "\n",
    "To add a transformer to the grid, use the `append` method with a `TransformerArray` object. This method adds a new transformer between specified nodes.\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from power_grid_model_ds.arrays import TransformerArray\n",
    "\n",
    "new_transformer_array = TransformerArray.zeros(1)\n",
    "new_transformer_array.from_node = 102\n",
    "new_transformer_array.to_node = 105\n",
    "grid.append(new_transformer_array)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "After adding the transformer, the total number of transformers in the grid increases by one.\n",
    "\n",
    "### Deleting a Transformer\n",
    "\n",
    "To delete a transformer from the grid, use the `delete_branch` method with the target transformer array.\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "target_transformer = grid.transformer.get(301)\n",
    "grid.delete_branch(branch=target_transformer)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "After deleting the transformer, the total number of transformers in the grid decreases by one.\n",
    "\n",
    "## Branch Activation and Deactivation\n",
    "\n",
    "### Activating a Branch\n",
    "\n",
    "To activate an inactive branch, use the `make_active` method with the target branch array.\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "target_line = grid.line.get(203)\n",
    "grid.make_active(branch=target_line)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "After activating the branch, its `from_status` and `to_status` are set to active, and the branch is added to the active graph.\n",
    "\n",
    "### Deactivating a Branch\n",
    "\n",
    "To deactivate an active branch, use the `make_inactive` method with the target branch array.\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "target_line = grid.line.get(203)\n",
    "grid.make_inactive(branch=target_line)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "After deactivating the branch, its `from_status` or `to_status` is set to inactive, and the branch is removed from the active graph.\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Comparing Grids\n",
    "\n",
    "Use Python's equality operator to quickly check whether two grids contain identical array data. The comparison inspects every array stored on the container and ignores differences inside `grid.graphs`, so it is perfect for validating serialized data or fixtures. If any field differs, the expression immediately returns `False`."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from power_grid_model_ds import Grid\n",
    "\n",
    "reference_grid = Grid.from_txt(\"1 2\", \"2 3 line\")\n",
    "candidate_grid = Grid.from_txt(\"1 2\", \"2 3 line\")\n",
    "\n",
    "print(f\"Grid equality (arrays only) before changes: {reference_grid == candidate_grid}\")\n",
    "\n",
    "candidate_grid.make_inactive(candidate_grid.line.get(4))\n",
    "print(f\"Grid equality after deactivating line 4: {reference_grid == candidate_grid}\")"
   ]
  }
 ],
 "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"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 4
}