diff --git a/docs/qcfractal/source/quickstart.ipynb b/docs/qcfractal/source/quickstart.ipynb index f0959164f..3779de9d8 100644 --- a/docs/qcfractal/source/quickstart.ipynb +++ b/docs/qcfractal/source/quickstart.ipynb @@ -6,7 +6,9 @@ "source": [ "# Quickstart Tutorial\n", "\n", - "This tutorial will go over general `qcfractal` usage to give a feel for the ecosystem. In this tutorial, we employ Snowflake, a simple QCFractal stack which runs on a local machine for demonstration and exploration purposes.\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", "## Installation\n", "\n", @@ -27,8 +29,9 @@ "## Importing QCFractal\n", "\n", "First let us import two items from the ecosystem:\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", + "\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." ] @@ -49,7 +52,8 @@ "source": [ "We can now build a temporary server which acts just like a normal server, but we have a bit more direct control of it.\n", "\n", - "**Warning!** All data is lost when this notebook shuts down! This is for demonstration purposes only!" + "**Warning!** All data is lost when this notebook shuts down! This is for demonstration purposes only!\n", + "For information about how to setup a permanent QCFractal server, see the [Setup Quickstart Guide](setup_quickstart.rst). " ] }, { @@ -85,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." ] }, { @@ -124,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. " ] }, { @@ -235,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).)" ] }, { @@ -253,7 +266,7 @@ } ], "source": [ - "options = {\n", + "spec = {\n", " \"keywords\": None,\n", " \"qc_spec\": {\n", " \"driver\": \"gradient\",\n", @@ -264,7 +277,7 @@ "}\n", "\n", "# Ask the server to compute a new computation\n", - "r = client.add_procedure(\"optimization\", \"geometric\", options, [mol])\n", + "r = client.add_procedure(\"optimization\", \"geometric\", spec, [mol])\n", "print(r)\n", "print(r.ids)" ] @@ -273,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:" ] }, { @@ -291,7 +306,7 @@ } ], "source": [ - "r2 = client.add_procedure(\"optimization\", \"geometric\", options, [mol])\n", + "r2 = client.add_procedure(\"optimization\", \"geometric\", spec, [mol])\n", "print(r)\n", "print(r.ids)" ] @@ -302,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", @@ -334,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." ] @@ -529,7 +544,7 @@ "source": [ "## Collections\n", "\n", - "Submitting individual procedures or single quantum chemistry tasks is not typically done as it becomes hard to track individual ``Tasks``. To help resolve this, ``Collections`` are different ways of organizing standard computations so that many tasks can be referenced in a more human-friendly way. In this particular case, we will be exploring an intermolecular potential dataset.\n", + "Submitting individual procedures or single quantum chemistry tasks is not typically done as it becomes hard to track individual tasks. To help resolve this, ``Collections`` are different ways of organizing standard computations so that many tasks can be referenced in a more human-friendly way. In this particular case, we will be exploring an intermolecular potential dataset.\n", "\n", "To begin, we will create a new dataset and add a few intermolecular interactions to it." ] @@ -1205,6 +1220,7 @@ "metadata": {}, "source": [ "This is only the very beginning of what you can do with QCFractal! Explore the documentation to learn more capabilities.\n", + "In particular, see the [next section](setup_quickstart.rst) for a quickstart guide on how to set up QCFractal in production.\n", "\n", "If you like the project, consider starring us on [GitHub](https://github.com/MolSSI/QCFractal). If you have any questions, join our [Slack](https://join.slack.com/t/qcdb/shared_invite/enQtNDIzNTQ2OTExODk0LWM3OTgxN2ExYTlkMTlkZjA0OTExZDlmNGRlY2M4NWJlNDlkZGQyYWUxOTJmMzc3M2VlYzZjMjgxMDRkYzFmOTE) channel." ] @@ -1227,8 +1243,17 @@ "nbconvert_exporter": "python", "pygments_lexer": "ipython3", "version": "3.7.2" + }, + "pycharm": { + "stem_cell": { + "cell_type": "raw", + "source": [], + "metadata": { + "collapsed": false + } + } } }, "nbformat": 4, "nbformat_minor": 2 -} +} \ No newline at end of file diff --git a/qcfractal/snowflake.py b/qcfractal/snowflake.py index 8d491ec9c..b176157c0 100644 --- a/qcfractal/snowflake.py +++ b/qcfractal/snowflake.py @@ -133,7 +133,9 @@ def __init__(self, query_limit=int(1.e6)) if self._storage: - self.logger.warning("Warning! This is a temporary instance, data will be lost upon shutdown.") + self.logger.warning("Warning! This is a temporary instance, data will be lost upon shutdown. " + "For information about how to set up a permanent QCFractal instance, see " + "http://docs.qcarchive.molssi.org/projects/qcfractal/en/latest/setup_quickstart.html") if start_server: self.start(start_loop=False)