submission_basics.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "id": "d60cc0ff",
   "metadata": {},
   "source": [
    "# QCArchive - Submitting calculations\n",
    "\n",
    "This notebook shows the basics of submitting calculations through the client (outside of a dataset)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "17936106",
   "metadata": {},
   "outputs": [],
   "source": [
    "import qcportal as ptl\n",
    "from qcportal.molecules import Molecule"
   ]
  },
  {
   "cell_type": "markdown",
   "source": [
    "## Create a client object and connect to the demo server\n",
    "\n",
    "The `PortalClient` is how you interact with the server, including querying records and submitting computations.\n",
    "\n",
    "The demo server allows for unauthenticated guest access, so no username/password is necessary to read from the server. However, you will\n",
    "need to log in to submit or modify computations"
   ],
   "metadata": {
    "collapsed": false
   }
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "6f8e54fd",
   "metadata": {},
   "outputs": [],
   "source": [
    "client = ptl.PortalClient(\"https://qcademo.molssi.org\", username=\"YOUR_USERNAME\", password=\"YOUR_PASSWORD\")"
   ]
  },
  {
   "cell_type": "markdown",
   "source": [
    "We are going to submit a singlepoint calculation.\n",
    "\n",
    "First, we create a molecule (QCElemental molecule). This is a hydrogen molecule with a bond distance of 1.0 bohr."
   ],
   "metadata": {
    "collapsed": false
   }
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "d2a92faa",
   "metadata": {},
   "outputs": [],
   "source": [
    "mol = Molecule(symbols=['h', 'h'], geometry=[[0.0, 0.0, 0.0, 0.0, 0.0, 1.0]])"
   ]
  },
  {
   "cell_type": "markdown",
   "source": [
    "Now submit the computation. This sends it to the server, where it is queued for computation. This will eventually be picked up by a worker\n",
    "if there is a worker that can handle it (proper programs installed, etc).\n",
    "\n",
    "The methods for adding computations (like `add_singlepoints`) take a list of molecules and the details of how to run the computation. We only have one molecule for now.\n",
    "\n",
    "* **program** = use this program to run the computation\n",
    "* **driver** = the main type of computation to run (energy, gradient, properties, etc)\n",
    "* **method**/**basis** = the computational model to use\n",
    "\n",
    "All `add_` functions return two objects. The first is metadata about the addition, and second is a list of record ids - we will only have one because we only submitted one molecule.\n",
    "We can use these IDs later to retrieve the record."
   ],
   "metadata": {
    "collapsed": false
   }
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "outputs": [],
   "source": [
    "meta, record_ids = client.add_singlepoints([mol], program='psi4', driver='energy', method='b3lyp', basis='def2-tzvp')"
   ],
   "metadata": {
    "collapsed": false
   }
  },
  {
   "cell_type": "markdown",
   "source": [
    "### Metadata\n",
    "\n",
    "The metadata object returned contains a couple important fields\n",
    "\n",
    "* **error_description** - An string of any major error that occurred\n",
    "* **errors** - Per-index error\n",
    "* **inserted_idx** - Indices (of the molecule list) that were inserted\n",
    "* **existing_idx** - Indices (of the molecule list) that already existed on the server\n",
    "\n",
    "The fields in the metadata refer to the index of a particular computation in our input. In this case, it refers to the index\n",
    "of the molecule in the molecule list, since there is one-to-one correspondence between molecules and computations.\n",
    "\n",
    "For example, if `inserted_idx=[2, 3]` and `existing_idx=[0, 1, 4]`, that means that records with this specification and molecules `mol[0]`, `mol[1]`, and `mol[4]` already exist\n",
    "on the server, and `mol[2]` and `mol[3]` are new computations."
   ],
   "metadata": {
    "collapsed": false
   }
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "outputs": [],
   "source": [
    "print(meta)"
   ],
   "metadata": {
    "collapsed": false
   }
  },
  {
   "cell_type": "markdown",
   "source": [
    "### The IDs\n",
    "\n",
    "The IDs are returned in the same order as the molecule list we passed in. In this case, we only have one."
   ],
   "metadata": {
    "collapsed": false
   }
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "outputs": [],
   "source": [
    "print(record_ids)"
   ],
   "metadata": {
    "collapsed": false
   }
  },
  {
   "cell_type": "markdown",
   "source": [
    "Using that ID, we can get the record and view the information as usual"
   ],
   "metadata": {
    "collapsed": false
   }
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "outputs": [],
   "source": [
    "record = client.get_records(record_ids[0])\n",
    "print(record.status)"
   ],
   "metadata": {
    "collapsed": false
   }
  }
 ],
 "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.9.13"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 5
}