Skip to content

Commit

Permalink
Merge pull request #366 from mattwelborn/issue-289
Browse files Browse the repository at this point in the history 
Quickstart tutorial enhancements (issue #289)
  • Loading branch information
@dgasmith
dgasmith committed Aug 16, 2019
2 parents 81f8731 + 40f7293 commit e30cef0
Show file tree
Hide file tree
Showing 2 changed files with 43 additions and 16 deletions.
55 changes: 40 additions & 15 deletions docs/qcfractal/source/quickstart.ipynb
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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",
Expand All @@ -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."
]
Expand All @@ -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). "
]
},
{
Expand Down Expand Up @@ -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."
]
},
{
Expand Down Expand Up @@ -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. "
]
},
{
Expand Down Expand Up @@ -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).)"
]
},
{
Expand All @@ -253,7 +266,7 @@
}
],
"source": [
"options = {\n",
"spec = {\n",
" \"keywords\": None,\n",
" \"qc_spec\": {\n",
" \"driver\": \"gradient\",\n",
Expand All @@ -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)"
]
Expand All @@ -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:"
]
},
{
Expand All @@ -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)"
]
Expand All @@ -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",
Expand Down Expand Up @@ -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."
]
Expand Down Expand Up @@ -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."
]
Expand Down Expand Up @@ -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."
]
Expand All @@ -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
}
}
4 changes: 3 additions & 1 deletion qcfractal/snowflake.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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)
Expand Down

0 comments on commit e30cef0

Please sign in to comment.