.. _How to guides:

How-to guides
=============
The tools of ASR can be combined to perform complicated tasks with little
effort. Below you will find the recommended procedures to perform common
tasks within the ASR framework.

.. contents:: List of available how-to guides

How-to: Make a screening study
------------------------------
A screening study what we call a simultaneous automatic study of many materials. ASR
has a set of tools to make such studies easy to handle. Suppose we have an ASE
database that contain many atomic structures. In this case we take OQMD12 database
that contain all unary and binary compounds on the convex hull.

The first thing we do is to get the database::

  $ mkdir ~/oqmd12 && cd ~/oqmd12
  $ wget https://cmr.fysik.dtu.dk/_downloads/oqmd12.db

We then use the `unpackdatabase` function of ASR to unpack the database into a
directory tree::

  $ asr run "setup.unpackdatabase oqmd12.db -s u=False --run"

(we have made the selection `u=False` since we are not interested in the DFT+U values).
This function produces a new folder `~oqmd12/tree/` where you can find the tree. 
To see the contents of the tree it is recommended to use the linux command `tree`::

  $ tree tree/

You will see that the unpacking of the database has produced many `unrelaxed.json`
files that contain the unrelaxed atomic structures. Because we don't know the
magnetic structure of the materials we also want to sample different magnetic structOBures.
This can be done with the `magnetize` function of asr::

  $ asr run --dry-run setup.magnetize */*/*/*/

We use the `run` function because that gives us the option to deal
with many folders at once. You are now ready to run a workflow on the
entire tree.

XXX Set up workflow.

  $ cat workflow.py

This workflow relaxes the structures and if the `convex_hull` recipe
calculates the heat of formation the workflow will make sure that the
bandstructure is calculated. We now ask `myqueue` what jobs it wants
to run.::

  $ mq workflow -z workflow.py tree/*/*/*/*/

To submit the jobs simply remove the `-z`, and run the command again.

How-to: Make a convergence study
--------------------------------
When you have created a new recipe it is highly likely that you would have to
make a convergence study of the parameters in your such that you have proof that
your choice of parameters are converged. The tools of ASR makes it easier to
conduct such convergence studies. ASR has a built-in database with materials
that could be relevant to investigate in your convergence tests. These materials
can be retrieved using the `setup.materials` recipe. See
`asr help setup.materials` for more information. For example, to convergence
check the parameters of `asr.relax` you can do the following.::


  $ mkdir convergence-test && cd convergence-test
  $ asr run setup.materials
  $ asr run "setup.unpackdatabase materials.json --tree-structure materials/{formula:metal} --run"
  $ cd materials/
  $ asr run "setup.scanparams asr.relax:ecut 600 700 800 asr.relax:kptdensity 4 5 6" */
  $ mq submit asr.relax@24:10h */*/


When the calculations are done you can collect all results into a database and
inspect them::

  $ cd convergence-test
  $ asr run "database.collect */*/"
  $ asr run "database.app database.db"


How-to: Collect a tree to folders and open in browser
-----------------------------------------------------
Suppose you have a set of folders with a structure like::

  tree/A/Mn/
  tree/AB/MnI2/
  tree/*/*/
  etc.

Then collect the database with::

  $ asr run "database.fromtree tree/*/*/"

And open a local web server with::

  $ asr run "database.app database.db"

Now browse it with::

  $ firefox localhost:5000


How-to: Submit a recipe with `MyQueue`
--------------------------------------
It is also recommended to use these recipes together with the `myqueue`
job managing package. We assume that you have installed the `myqueue`-package
and are familiar with its usage. If you are not, then take a look at its excellent
documentation. To submit a job that relaxes a structure simply do::

  $ mq submit asr.relax -R 24:10h


How-to: Generate figures from a certain recipe
----------------------------------------------

Let's assume that the bandstructure has been calculated and you want
to display the results. Then it's as simple as using the `asr results`
cli sub-command::

  $ asr results asr.bandstructure

which will save any figures generated by the webpanel associated with
`asr.bandstructure` in the current folder.


How-to: Continue working on a packaged project
----------------------------------------------

Suppose that you want to continue working on a previously packaged
project, for example, to calculate a new property. Suppose the project
is packaged as `project.db`, and that you only want to unpack the
ground state results since your new recipe does not need other results
in the database.

To unpack the project do::

  $ asr run "database.totree project.db --run --patterns results-asr.gs.json,gs.gpw"

Then perform the calculations needed in the unpacked folders. When
calculations are done package them and merge the databases::

  $ asr run "database.fromtree tree/*/*/*/"
  $ asr run "database.merge project.db database.db merged.db"

The databases have now been merged into a new database called
`merged.db`.
