diff --git a/docs/qcfractal/source/quickstart.ipynb b/docs/qcfractal/source/quickstart.ipynb index 1ffaa6d72..3779de9d8 100644 --- a/docs/qcfractal/source/quickstart.ipynb +++ b/docs/qcfractal/source/quickstart.ipynb @@ -6,7 +6,7 @@ "source": [ "# Quickstart Tutorial\n", "\n", - "This tutorial will go over general `qcfractal` usage to give a feel for the ecosystem. \n", + "This tutorial will go over general QCFractal usage to give a feel for the ecosystem. \n", "In this tutorial, we employ Snowflake, a simple QCFractal stack which runs on a local machine \n", "for demonstration and exploration purposes.\n", "\n", @@ -30,8 +30,8 @@ "\n", "First let us import two items from the ecosystem:\n", "\n", - " * `FractalSnowflakeHandler` - This is a `FractalServer` that is temporary and is used for trying out new things.\n", - " * `qcfractal.interface` is the `qcportal` module, but if using `qcfractal` it is best to import it locally.\n", + " * [FractalSnowflakeHandler](http://docs.qcarchive.molssi.org/projects/qcfractal/en/latest/api/qcfractal.FractalSnowflakeHandler.html?highlight=FractalSnowflakeHandler) - This is a [FractalServer](https://qcarchivetutorials.readthedocs.io/projects/qcfractal/en/latest/api/qcfractal.FractalServer.html) that is temporary and is used for trying out new things.\n", + " * `qcfractal.interface` is the [QCPortal](https://github.com/MolSSI/QCPortal) module, but if using QCFractal it is best to import it locally.\n", " \n", "Typically we alias `qcportal` as `ptl`. We will do the same for `qcfractal.interface` so that the code can be used anywhere." ] @@ -89,7 +89,9 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "We can then build a typical `FractalClient` to automatically connect to this server using the `client()` helper command. Note that the server names and addresses are identical in both the server and client." + "We can then build a typical [FractalClient](http://docs.qcarchive.molssi.org/projects/qcportal/en/latest/client.html?highlight=fractalclient#portal-client) \n", + "to automatically connect to this server using the [client()](http://docs.qcarchive.molssi.org/projects/qcfractal/en/latest/api/qcfractal.FractalSnowflakeHandler.html?highlight=FractalSnowflakeHandler#qcfractal.FractalSnowflakeHandler.client) helper command. \n", + "Note that the server names and addresses are identical in both the server and client." ] }, { @@ -128,7 +130,10 @@ "source": [ "## Adding and Querying data\n", "\n", - "A server starts with no data, so let's add some! We can do this by adding a water molecule at a poor geometry from XYZ coordinates. Note that all internal QCFractal values are stored and used in atomic units; whereas, the standard `Molecule.from_data` assumes an input of Angstroms. We can switch this back to Bohr by adding a `units` command in the text string. " + "A server starts with no data, so let's add some! We can do this by adding a water molecule at a poor geometry from XYZ coordinates. \n", + "Note that all internal QCFractal values are stored and used in atomic units; \n", + "whereas, the standard [Molecule.from_data()](http://docs.qcarchive.molssi.org/projects/qcelemental/en/latest/molecule.html?highlight=from_data#creation) assumes an input of Angstroms. \n", + "We can switch this back to Bohr by adding a `units` command in the text string. " ] }, { @@ -239,7 +244,11 @@ "\n", "We originally installed `psi4` and `geometric`, so we can use these programs to perform a geometry optimization. In QCFractal, we call a geometry optimization a `procedure`, where `procedure` is a generic term for a higher level operation that will run multiple individual quantum chemistry energy, gradient, or Hessian evaluations. Other `procedure` examples are finite-difference computations, n-body computations, and torsiondrives.\n", "\n", - "We provide a JSON-like input to the `client.add_procedure` command to specify the method, basis, and program to be used. The `qc_spec` field is used in all procedures to determine the underlying quantum chemistry method behind the individual procedure. In this way, we can use any program or method that returns a energy or gradient quantity to run our geometry optimization!" + "We provide a JSON-like input to the [client.add_procedure()](http://docs.qcarchive.molssi.org/projects/qcportal/en/latest/client-api.html?highlight=add_procedure#qcportal.FractalClient.add_procedure)\n", + " command to specify the method, basis, and program to be used. \n", + "The `qc_spec` field is used in all procedures to determine the underlying quantum chemistry method behind the individual procedure.\n", + "In this way, we can use any program or method that returns a energy or gradient quantity to run our geometry optimization!\n", + "(See also [add_compute()](http://docs.qcarchive.molssi.org/projects/qcportal/en/latest/client-api.html?highlight=add_procedure#qcportal.FractalClient.add_compute).)" ] }, { @@ -277,7 +286,9 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "We can see that we submitted a single task to be evaluated and the server has not seen this particular procedure before. The `ids` field returns the unique `id` of the procedure. Different procedures will always have a unique `id`, while identical procedures will always return the same `id`. We can submit the same procedure again to see this effect:" + "We can see that we submitted a single task to be evaluated and the server has not seen this particular procedure before. \n", + "The `ids` field returns the unique `id` of the procedure. Different procedures will always have a unique `id`, while identical procedures will always return the same `id`. \n", + "We can submit the same procedure again to see this effect:" ] }, { @@ -306,7 +317,7 @@ "source": [ "## Querying Procedures\n", "\n", - "Once a task is submitted, it will be placed in the compute queue and evaluated. In this particular case the `FractalSnowflakeHandler` uses your local hardware to evaluate these jobs. We recommend avoiding large tasks!\n", + "Once a task is submitted, it will be placed in the compute queue and evaluated. In this particular case the [FractalSnowflakeHandler](http://docs.qcarchive.molssi.org/projects/qcfractal/en/latest/api/qcfractal.FractalSnowflakeHandler.html?highlight=FractalSnowflakeHandler) uses your local hardware to evaluate these jobs. We recommend avoiding large tasks!\n", "\n", "In general, the server can handle anywhere between laptop-scale resources to many hundreds of thousands of concurrent cores at many physical locations. The amount of resources to connect is up to you and the amount of compute that you require.\n", "\n", @@ -338,7 +349,7 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "This `OptimizationRecord` object has many different fields attached to it so that all quantities involved in the computation can be explored. For this example, let us pull the final molecule (optimized structure) and inspect the physical dimensions.\n", + "This [OptimizationRecord](http://docs.qcarchive.molssi.org/projects/qcportal/en/latest/record-api.html?highlight=optimizationrecord#qcportal.models.OptimizationRecord) object has many different fields attached to it so that all quantities involved in the computation can be explored. For this example, let us pull the final molecule (optimized structure) and inspect the physical dimensions.\n", "\n", "Note: if the status does not say `COMPLETE`, these fields will not be available. Try querying the procedure again in a few seconds to see if the task completed in the background." ]