{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Precautions"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Here we discuss some precautions when using mdapy."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "[Taichi] version 1.7.1, llvm 15.0.1, commit 0f143b2f, win, python 3.10.14\n",
      "[Taichi] Starting on arch=x64\n"
     ]
    }
   ],
   "source": [
    "import mdapy as mp\n",
    "import polars as pl\n",
    "mp.init()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "'0.11.1'"
      ]
     },
     "execution_count": 2,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "mp.__version__"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "metadata": {},
   "outputs": [],
   "source": [
    "system = mp.System('../../../example/solidliquid.data')"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "Filename: ../../../example/solidliquid.data\n",
       "Atom Number: 8192\n",
       "Simulation Box:\n",
       "[[52.01907282  0.          0.        ]\n",
       " [ 0.         52.01907282  0.        ]\n",
       " [ 0.          0.         52.01907282]\n",
       " [-0.39698541 -0.39698541 -0.39698541]]\n",
       "TimeStep: 0\n",
       "Boundary: [1, 1, 1]\n",
       "Particle Information:\n",
       "shape: (8_192, 8)\n",
       "┌──────┬──────┬───────────┬───────────┬───────────┬───────────┬──────────┬───────────┐\n",
       "│ id   ┆ type ┆ x         ┆ y         ┆ z         ┆ vx        ┆ vy       ┆ vz        │\n",
       "│ ---  ┆ ---  ┆ ---       ┆ ---       ┆ ---       ┆ ---       ┆ ---      ┆ ---       │\n",
       "│ i64  ┆ i64  ┆ f64       ┆ f64       ┆ f64       ┆ f64       ┆ f64      ┆ f64       │\n",
       "╞══════╪══════╪═══════════╪═══════════╪═══════════╪═══════════╪══════════╪═══════════╡\n",
       "│ 7913 ┆ 1    ┆ 2.64108   ┆ 3.2152    ┆ 1.74197   ┆ 2.90096   ┆ 1.72875  ┆ -1.77975  │\n",
       "│ 4098 ┆ 1    ┆ -0.091857 ┆ 0.4658    ┆ 0.936675  ┆ -0.166803 ┆ 0.959803 ┆ 3.70312   │\n",
       "│ 4414 ┆ 1    ┆ 51.3076   ┆ 2.93742   ┆ 2.12484   ┆ 4.50605   ┆ -1.06924 ┆ -1.41931  │\n",
       "│ 4    ┆ 1    ┆ 3.57773   ┆ -0.024408 ┆ 2.31072   ┆ -6.04709  ┆ 5.23451  ┆ 9.18538   │\n",
       "│ 37   ┆ 1    ┆ 45.219    ┆ 19.5654   ┆ -0.241386 ┆ -5.20306  ┆ 3.79694  ┆ -2.15249  │\n",
       "│ …    ┆ …    ┆ …         ┆ …         ┆ …         ┆ …         ┆ …        ┆ …         │\n",
       "│ 1936 ┆ 1    ┆ 32.3371   ┆ 29.817    ┆ 25.6971   ┆ 5.55254   ┆ -3.03374 ┆ 1.8186    │\n",
       "│ 5887 ┆ 1    ┆ 30.7777   ┆ 5.709     ┆ 25.6752   ┆ -3.2635   ┆ -5.90409 ┆ 4.00862   │\n",
       "│ 3968 ┆ 1    ┆ 22.2868   ┆ 25.2811   ┆ 51.5631   ┆ 6.79441   ┆ -7.16023 ┆ -0.666231 │\n",
       "│ 5927 ┆ 1    ┆ 30.8122   ┆ 12.6453   ┆ 25.6768   ┆ 1.40187   ┆ 0.723993 ┆ 3.83902   │\n",
       "│ 1888 ┆ 1    ┆ 13.1155   ┆ 28.3524   ┆ 25.6479   ┆ 5.00834   ┆ -2.91066 ┆ 5.65182   │\n",
       "└──────┴──────┴───────────┴───────────┴───────────┴───────────┴──────────┴───────────┘"
      ]
     },
     "execution_count": 4,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "system"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Check the position information"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 5,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "array([[ 2.64108e+00,  3.21520e+00,  1.74197e+00],\n",
       "       [-9.18574e-02,  4.65800e-01,  9.36675e-01],\n",
       "       [ 5.13076e+01,  2.93742e+00,  2.12484e+00],\n",
       "       [ 3.57773e+00, -2.44078e-02,  2.31072e+00],\n",
       "       [ 4.52190e+01,  1.95654e+01, -2.41386e-01]])"
      ]
     },
     "execution_count": 5,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "system.pos[:5]"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Generally speaking, we do not need to change the position. So the pos information is inmutable for users.\n",
    "If you try to change it, it will raise an error. This is for data safety."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 6,
   "metadata": {},
   "outputs": [
    {
     "ename": "ValueError",
     "evalue": "assignment destination is read-only",
     "output_type": "error",
     "traceback": [
      "\u001b[1;31m---------------------------------------------------------------------------\u001b[0m",
      "\u001b[1;31mValueError\u001b[0m                                Traceback (most recent call last)",
      "Cell \u001b[1;32mIn[6], line 1\u001b[0m\n\u001b[1;32m----> 1\u001b[0m \u001b[43msystem\u001b[49m\u001b[38;5;241;43m.\u001b[39;49m\u001b[43mpos\u001b[49m\u001b[43m[\u001b[49m\u001b[38;5;241;43m0\u001b[39;49m\u001b[43m,\u001b[49m\u001b[43m \u001b[49m\u001b[38;5;241;43m0\u001b[39;49m\u001b[43m]\u001b[49m \u001b[38;5;241m=\u001b[39m \u001b[38;5;241m1.\u001b[39m\n",
      "\u001b[1;31mValueError\u001b[0m: assignment destination is read-only"
     ]
    }
   ],
   "source": [
    "system.pos[0, 0] = 1."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "If you really need to change ths positions for system object, you can modify the system.data and update it mannually!!!\n",
    "Considering you want let atoms with z < 10 moves right 2 along x, you can do like below:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 7,
   "metadata": {},
   "outputs": [],
   "source": [
    "system.update_data(\n",
    "    system.data.\n",
    "    with_columns(\n",
    "    pl.when(pl.col('z')<10).\n",
    "    then(pl.col('x')+2).\n",
    "    otherwise(pl.col('x')).\n",
    "    alias('x')), \n",
    "    update_pos=True) \n",
    "# The first parameter is a new Dataframe, the second indicates mdapy will update the position information."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 8,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/html": [
       "<div><style>\n",
       ".dataframe > thead > tr,\n",
       ".dataframe > tbody > tr {\n",
       "  text-align: right;\n",
       "  white-space: pre-wrap;\n",
       "}\n",
       "</style>\n",
       "<small>shape: (5, 8)</small><table border=\"1\" class=\"dataframe\"><thead><tr><th>id</th><th>type</th><th>x</th><th>y</th><th>z</th><th>vx</th><th>vy</th><th>vz</th></tr><tr><td>i64</td><td>i64</td><td>f64</td><td>f64</td><td>f64</td><td>f64</td><td>f64</td><td>f64</td></tr></thead><tbody><tr><td>7913</td><td>1</td><td>4.64108</td><td>3.2152</td><td>1.74197</td><td>2.90096</td><td>1.72875</td><td>-1.77975</td></tr><tr><td>4098</td><td>1</td><td>1.9081426</td><td>0.4658</td><td>0.936675</td><td>-0.166803</td><td>0.959803</td><td>3.70312</td></tr><tr><td>4414</td><td>1</td><td>53.3076</td><td>2.93742</td><td>2.12484</td><td>4.50605</td><td>-1.06924</td><td>-1.41931</td></tr><tr><td>4</td><td>1</td><td>5.57773</td><td>-0.024408</td><td>2.31072</td><td>-6.04709</td><td>5.23451</td><td>9.18538</td></tr><tr><td>37</td><td>1</td><td>47.219</td><td>19.5654</td><td>-0.241386</td><td>-5.20306</td><td>3.79694</td><td>-2.15249</td></tr></tbody></table></div>"
      ],
      "text/plain": [
       "shape: (5, 8)\n",
       "┌──────┬──────┬───────────┬───────────┬───────────┬───────────┬──────────┬──────────┐\n",
       "│ id   ┆ type ┆ x         ┆ y         ┆ z         ┆ vx        ┆ vy       ┆ vz       │\n",
       "│ ---  ┆ ---  ┆ ---       ┆ ---       ┆ ---       ┆ ---       ┆ ---      ┆ ---      │\n",
       "│ i64  ┆ i64  ┆ f64       ┆ f64       ┆ f64       ┆ f64       ┆ f64      ┆ f64      │\n",
       "╞══════╪══════╪═══════════╪═══════════╪═══════════╪═══════════╪══════════╪══════════╡\n",
       "│ 7913 ┆ 1    ┆ 4.64108   ┆ 3.2152    ┆ 1.74197   ┆ 2.90096   ┆ 1.72875  ┆ -1.77975 │\n",
       "│ 4098 ┆ 1    ┆ 1.9081426 ┆ 0.4658    ┆ 0.936675  ┆ -0.166803 ┆ 0.959803 ┆ 3.70312  │\n",
       "│ 4414 ┆ 1    ┆ 53.3076   ┆ 2.93742   ┆ 2.12484   ┆ 4.50605   ┆ -1.06924 ┆ -1.41931 │\n",
       "│ 4    ┆ 1    ┆ 5.57773   ┆ -0.024408 ┆ 2.31072   ┆ -6.04709  ┆ 5.23451  ┆ 9.18538  │\n",
       "│ 37   ┆ 1    ┆ 47.219    ┆ 19.5654   ┆ -0.241386 ┆ -5.20306  ┆ 3.79694  ┆ -2.15249 │\n",
       "└──────┴──────┴───────────┴───────────┴───────────┴───────────┴──────────┴──────────┘"
      ]
     },
     "execution_count": 8,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "system.data.head() # x[0] from 2.64108 to 4.64108"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 9,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "array([[ 4.6410800e+00,  3.2152000e+00,  1.7419700e+00],\n",
       "       [ 1.9081426e+00,  4.6580000e-01,  9.3667500e-01],\n",
       "       [ 5.3307600e+01,  2.9374200e+00,  2.1248400e+00],\n",
       "       [ 5.5777300e+00, -2.4407800e-02,  2.3107200e+00],\n",
       "       [ 4.7219000e+01,  1.9565400e+01, -2.4138600e-01]])"
      ]
     },
     "execution_count": 9,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "system.pos[:5] # updated correspondingly."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "velocity is all the same with position."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 10,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "array([[ 2.90096 ,  1.72875 , -1.77975 ],\n",
       "       [-0.166803,  0.959803,  3.70312 ],\n",
       "       [ 4.50605 , -1.06924 , -1.41931 ],\n",
       "       [-6.04709 ,  5.23451 ,  9.18538 ],\n",
       "       [-5.20306 ,  3.79694 , -2.15249 ]])"
      ]
     },
     "execution_count": 10,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "system.vel[:5]"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "If you try to modify it directly, raise an error."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 11,
   "metadata": {},
   "outputs": [
    {
     "ename": "ValueError",
     "evalue": "assignment destination is read-only",
     "output_type": "error",
     "traceback": [
      "\u001b[1;31m---------------------------------------------------------------------------\u001b[0m",
      "\u001b[1;31mValueError\u001b[0m                                Traceback (most recent call last)",
      "Cell \u001b[1;32mIn[11], line 1\u001b[0m\n\u001b[1;32m----> 1\u001b[0m \u001b[43msystem\u001b[49m\u001b[38;5;241;43m.\u001b[39;49m\u001b[43mvel\u001b[49m\u001b[43m[\u001b[49m\u001b[38;5;241;43m0\u001b[39;49m\u001b[43m,\u001b[49m\u001b[43m \u001b[49m\u001b[38;5;241;43m0\u001b[39;49m\u001b[43m]\u001b[49m \u001b[38;5;241m=\u001b[39m \u001b[38;5;241m3.5\u001b[39m\n",
      "\u001b[1;31mValueError\u001b[0m: assignment destination is read-only"
     ]
    }
   ],
   "source": [
    "system.vel[0, 0] = 3.5"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "You can change the data to modify the velocities."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 12,
   "metadata": {},
   "outputs": [],
   "source": [
    "system.data[0, 'vx'] = 3.5"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 13,
   "metadata": {},
   "outputs": [],
   "source": [
    "system.update_vel() # Update the velocity mannually."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "system.data.head()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 14,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/html": [
       "<div><style>\n",
       ".dataframe > thead > tr,\n",
       ".dataframe > tbody > tr {\n",
       "  text-align: right;\n",
       "  white-space: pre-wrap;\n",
       "}\n",
       "</style>\n",
       "<small>shape: (5, 8)</small><table border=\"1\" class=\"dataframe\"><thead><tr><th>id</th><th>type</th><th>x</th><th>y</th><th>z</th><th>vx</th><th>vy</th><th>vz</th></tr><tr><td>i64</td><td>i64</td><td>f64</td><td>f64</td><td>f64</td><td>f64</td><td>f64</td><td>f64</td></tr></thead><tbody><tr><td>7913</td><td>1</td><td>4.64108</td><td>3.2152</td><td>1.74197</td><td>3.5</td><td>1.72875</td><td>-1.77975</td></tr><tr><td>4098</td><td>1</td><td>1.9081426</td><td>0.4658</td><td>0.936675</td><td>-0.166803</td><td>0.959803</td><td>3.70312</td></tr><tr><td>4414</td><td>1</td><td>53.3076</td><td>2.93742</td><td>2.12484</td><td>4.50605</td><td>-1.06924</td><td>-1.41931</td></tr><tr><td>4</td><td>1</td><td>5.57773</td><td>-0.024408</td><td>2.31072</td><td>-6.04709</td><td>5.23451</td><td>9.18538</td></tr><tr><td>37</td><td>1</td><td>47.219</td><td>19.5654</td><td>-0.241386</td><td>-5.20306</td><td>3.79694</td><td>-2.15249</td></tr></tbody></table></div>"
      ],
      "text/plain": [
       "shape: (5, 8)\n",
       "┌──────┬──────┬───────────┬───────────┬───────────┬───────────┬──────────┬──────────┐\n",
       "│ id   ┆ type ┆ x         ┆ y         ┆ z         ┆ vx        ┆ vy       ┆ vz       │\n",
       "│ ---  ┆ ---  ┆ ---       ┆ ---       ┆ ---       ┆ ---       ┆ ---      ┆ ---      │\n",
       "│ i64  ┆ i64  ┆ f64       ┆ f64       ┆ f64       ┆ f64       ┆ f64      ┆ f64      │\n",
       "╞══════╪══════╪═══════════╪═══════════╪═══════════╪═══════════╪══════════╪══════════╡\n",
       "│ 7913 ┆ 1    ┆ 4.64108   ┆ 3.2152    ┆ 1.74197   ┆ 3.5       ┆ 1.72875  ┆ -1.77975 │\n",
       "│ 4098 ┆ 1    ┆ 1.9081426 ┆ 0.4658    ┆ 0.936675  ┆ -0.166803 ┆ 0.959803 ┆ 3.70312  │\n",
       "│ 4414 ┆ 1    ┆ 53.3076   ┆ 2.93742   ┆ 2.12484   ┆ 4.50605   ┆ -1.06924 ┆ -1.41931 │\n",
       "│ 4    ┆ 1    ┆ 5.57773   ┆ -0.024408 ┆ 2.31072   ┆ -6.04709  ┆ 5.23451  ┆ 9.18538  │\n",
       "│ 37   ┆ 1    ┆ 47.219    ┆ 19.5654   ┆ -0.241386 ┆ -5.20306  ┆ 3.79694  ┆ -2.15249 │\n",
       "└──────┴──────┴───────────┴───────────┴───────────┴───────────┴──────────┴──────────┘"
      ]
     },
     "execution_count": 14,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "system.data.head() # vx[0] from 2.90096 to 3.5"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 15,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "array([[ 3.5     ,  1.72875 , -1.77975 ],\n",
       "       [-0.166803,  0.959803,  3.70312 ],\n",
       "       [ 4.50605 , -1.06924 , -1.41931 ],\n",
       "       [-6.04709 ,  5.23451 ,  9.18538 ],\n",
       "       [-5.20306 ,  3.79694 , -2.15249 ]])"
      ]
     },
     "execution_count": 15,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "system.vel[:5] # updated correspondingly."
   ]
  }
 ],
 "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.14"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 4
}