aiida-quantumespresso icon indicating copy to clipboard operation
aiida-quantumespresso copied to clipboard

📚 Docs: Add first version of `PwRelaxWorkChain` how to

Open mbercx opened this issue 1 year ago • 2 comments

First version of the How-to section on the PwRelaxWorkChain. Describes basic usage via the get_builder_from_protocol() method, as well as determining the basic degrees of freedom using the RelaxType enum.

mbercx avatar May 20 '23 16:05 mbercx

Thanks for the comments, @sphuber! This is exactly why I still left the PR as a WIP, to discuss how to properly structure the docs. 👍 📚

I completely agree that it is good to have a clear separation between tutorials and how-to's, although there will always be a bit of overlap. Also fine with rethinking the language. Let me have a crack at adapting this documentation, but also write down our policies on this so we can crystallise our approach.

mbercx avatar May 23 '23 15:05 mbercx

Thanks for this @mbercx !

I personally don't feel strongly about the language you choose here, but I do agree about the level of verbosity - I believe less is more here, both for users and for maintainers. As a first step, I would only add a tiny bit of extra information per worfklow - the minimum a new user needs to know which workflow to run, and any specific settings that cannot be left at their default values.

Here are my suggestions

  • Start the top-level howto section with anything that is general to all aiida-qe workflows (e.g. the get_builder_from_protocol pattern)
  • For the PwRelaxWorkChain something like this would suffice:

``python
from aiida_quantumespresso.workflows.pw.relax import PwRelaxWorkChain
from aiida_quantumespresso.common.types import RelaxType

builder = PwRelaxWorkChain.get_builder_from_protocol(
    code=orm.load_code('qe-7.2-pw@localhost'),
    structure=my_structure,  # StructureData
    relax_type=RelaxType.CELL # default
)
``

This will optimise both the positions of the atoms and the cell geometry using sensible defaults for plane-wave cutoff, k-point meshes, etc.

Options for the `RelaxType`:

* `POSITIONS`: Only the atomic positions are relaxed, cell is fixed.
* `SHAPE`: Only the cell shape is optimized at a fixed volume and fixed atomic positions.
* `CELL`: Only the cell is optimized, both shape and volume, while atomic positions are fixed.
* `POSITIONS_SHAPE`: Same as `SHAPE`  but atomic positions are relaxed as well.
* `POSITIONS_CELL`: Same as `CELL`  but atomic positions are relaxed as well.


.. autodoc of PwRelaxWorkChain 

ltalirz avatar May 30 '23 12:05 ltalirz