Text review and update (aiidalab#281)

The texts of information and instructions are updated based on the feedback from Nicola. Co-authored-by: Marnik Bercx <mbercx@gmail.com>
unkcpz · Sep 20, 2022 · 9d927a7 · 9d927a7
1 parent 6d24a37
commit 9d927a7
Show file tree

Hide file tree

Showing 8 changed files with 40 additions and 36 deletions.
diff --git a/aiidalab_qe/node_view.py b/aiidalab_qe/node_view.py
@@ -421,7 +421,7 @@ def __init__(self, node, **kwargs):
         self.title = ipw.HTML(
             f"""
             <hr style="height:2px;background-color:#2097F3;">
-            <h4>QE App Work Chain (pk: {self.node.pk}) &mdash;
+            <h4>QE App Workflow (pk: {self.node.pk}) &mdash;
                 {self.node.inputs.structure.get_formula()}
             </h4>
             """

diff --git a/aiidalab_qe/process.py b/aiidalab_qe/process.py
@@ -28,7 +28,9 @@ class WorkChainSelector(ipw.HBox):
     FMT_WORKCHAIN = "{wc.pk:6}{wc.ctime:>10}\t{wc.state:<16}\t{wc.formula} \t {wc.relax_info} \t {wc.properties_info}"
 
     def __init__(self, **kwargs):
-        self.work_chains_prompt = ipw.HTML("<b>Select workflow or start new:</b>&nbsp;")
+        self.work_chains_prompt = ipw.HTML(
+            "<b>Select computed workflow or start a new:</b>&nbsp;"
+        )
         self.work_chains_selector = ipw.Dropdown(
             options=[("New workflow...", self._NO_PROCESS)],
             layout=ipw.Layout(min_width="300px", flex="1 1 auto"),
@@ -124,7 +126,7 @@ def refresh_work_chains(self, _=None):
                     original_value = self.work_chains_selector.value
 
                     self.work_chains_selector.options = [
-                        ("New calculation...", self._NO_PROCESS)
+                        ("New workflow...", self._NO_PROCESS)
                     ] + [
                         (self.FMT_WORKCHAIN.format(wc=wc), wc.pk)
                         for wc in self.find_work_chains()

diff --git a/aiidalab_qe/pseudos.py b/aiidalab_qe/pseudos.py
@@ -16,24 +16,24 @@ class PseudoFamilySelector(ipw.VBox):
 
     description = ipw.HTML(
         """<div style="line-height: 140%; padding-top: 0px; padding-bottom: 10px">
-        The exchange-correlation function and pseudopotential library is set by
-        the <b>protocol</b> configured in the "WorkChain" tab. Here you can
+        The exchange-correlation functional and pseudopotential library is set by
+        the <b>protocol</b> configured in the "Workflow" tab. Here you can
         override the defaults if desired.</div>""",
         layout=ipw.Layout(max_width="60%"),
     )
 
     pseudo_family_prompt = ipw.HTML(
         """<div style="line-height: 140%; padding-top: 0px; padding-bottom: 10px; opacity:0.5;">
-        <b><a href="https://www.materialscloud.org/discover/sssp/table/precision"
-        target="_blank">Standard Solid-state pseudopotential</a> (SSSP) protocol</b></div>"""
+        <b><a href="https://www.materialscloud.org/discover/sssp/table/efficiency"
+        target="_blank">Standard solid-state pseudopotentials</a> (SSSP)</b></div>"""
     )
     pseudo_family_help = ipw.HTML(
         """<div style="line-height: 140%; padding-top: 10px; padding-bottom: 0px; opacity:0.5;">
-        If you are unsure what to choose, select 'SSSP efficiency', which for
+        If you are unsure, select 'SSSP efficiency', which for
         most calculations will produce sufficiently accurate results at
-        comparatively small computational cost. If your calculation requires a
+        comparatively small computational costs. If your calculations require a
         higher accuracy, select 'SSSP accuracy', which will be computationally
-        more expensive, but will produce even more accurate results.</div>"""
+        more expensive.</div>"""
     )
 
     dft_functional_prompt = ipw.HTML(
@@ -43,8 +43,7 @@ class PseudoFamilySelector(ipw.VBox):
     )
     dft_functional_help = ipw.HTML(
         """<div style="line-height: 140%; padding-top: 10px; padding-bottom: 10px; opacity:0.5;">
-        The exchange-correlation energy is calculated based on the charge
-        density using this functional. We currently provide support for two
+        The exchange-correlation energy is calculated functional. We currently provide support for two
         well-established generalised gradient approximation (GGA) functionals:
         PBE and PBEsol.</div>"""
     )

diff --git a/aiidalab_qe/report.py b/aiidalab_qe/report.py
@@ -34,13 +34,13 @@ def _generate_report_dict(qeapp_wc):
     run_pdos = builder_parameters.get("run_pdos")
 
     yield "relaxed", run_relax
-    yield "relax_method", builder_parameters["relax_type"].title()
+    yield "relax_method", builder_parameters["relax_type"]
     yield "bands_computed", run_bands
     yield "pdos_computed", run_pdos
 
     # Material settings
-    yield "material_magnetic", builder_parameters["spin_type"].title()
-    yield "electronic_type", builder_parameters["electronic_type"].title()
+    yield "material_magnetic", builder_parameters["spin_type"]
+    yield "electronic_type", builder_parameters["electronic_type"]
 
     # Calculation settings
     yield "protocol", builder_parameters["protocol"]

diff --git a/aiidalab_qe/static/welcome.jinja b/aiidalab_qe/static/welcome.jinja
@@ -9,10 +9,10 @@
 <div style="padding-top: 0px; padding-bottom: 0px; line-height: 140%;">
   <h3>Welcome to the AiiDAlab Quantum ESPRESSO app! 👋</h3>
 
-  The <a href="https://www.quantum-espresso.org/" target="_blank">Quantum ESPRESSO</a> app (or QE app for short) is a graphical interface for calculating material properties based on density-functional theory (DFT).
-  Each of the properties is calculated by workflows powered by the <a href="https://www.aiida.net/" target="_bland"> AiiDA engine</a>, and maintained in the <a href="https://aiida-quantumespresso.readthedocs.io/en/latest/" target="_blank"> Quantum ESPRESSO plugin</a> for AiiDA.
+  The <a href="https://www.quantum-espresso.org/" target="_blank">Quantum ESPRESSO</a> app (or QE app for short) is a graphical front end for calculating materials properties using Quantum ESPRESSO (QE).
+  Each property is calculated by workflows powered by the <a href="https://www.aiida.net/" target="_bland"> AiiDA engine</a>, and maintained in the <a href="https://aiida-quantumespresso.readthedocs.io/en/latest/" target="_blank"> Quantum ESPRESSO plugin</a> for AiiDA.
 
-  <p style="padding-top: 10px; padding-bottom: 10px;">The QE app allows you to calculate material properties in a simple 4-step process:</p>
+  <p style="padding-top: 10px; padding-bottom: 10px;">The QE app allows you to calculate properties in a simple 4-step process:</p>
 
   <ol style="list-style-type:none">
     <li style="padding-top: 2px; padding-bottom: 2px;">🔍 <b>Step 1:</b> Select the structure you want to run.</li>
@@ -21,7 +21,7 @@
     <li style="padding-top: 2px; padding-bottom: 2px;">🚀 <b>Step 4:</b> Submit your workflow.</li>
   </ol>
 
-  <p style="padding-top: 5px; padding-bottom: 5px;">New users can go straight to the first step and select their structure. Once you've already calculated some properties, you can select the corresponding workflow using the dropdown below.</p>
+  <p style="padding-top: 5px; padding-bottom: 5px;">New users can go straight to the first step and select their structure. Once you've already run some calculations, you can select the corresponding workflow using the dropdown below.</p>
   <p style="padding-top: 5px; padding-bottom: 5px;"><em>Happy computing! 🎉</em></p>
 </div>
 

diff --git a/aiidalab_qe/static/workflow_summary.jinja b/aiidalab_qe/static/workflow_summary.jinja
@@ -8,7 +8,7 @@
 
 <div class="row">
   <div class="column">
-    <h3>Workchain settings</h3>
+    <h3>Standard Settings</h3>
     <table>
       <tr>
         <td>Structure geometry optimized</td>
@@ -21,7 +21,7 @@
       </tr>
       {% endif %}
       <tr>
-        <td>Work chain protocol</td>
+        <td>Protocol</td>
         <td>{{ protocol }}</td>
       </tr>
       <tr>
@@ -36,7 +36,7 @@
     </table>
   </div>
   <div class="column">
-    <h3>Advanced settings</h3>
+    <h3>Advanced Settings</h3>
     <table>
       <tr>
         <td>Functional</td>

diff --git a/aiidalab_qe/steps.py b/aiidalab_qe/steps.py
@@ -48,13 +48,17 @@ class WorkChainSettings(ipw.VBox):
     )
     structure_help = ipw.HTML(
         """<div style="line-height: 140%; padding-top: 0px; padding-bottom: 5px">
-        By default, the workflow will optimize the provided geometry. Select "Structure
-        as is" if this is not desired. You can either optimize the atomic positions ("Full geometry")
-        and unit cell, or atomic positions only ("Atomic positions"). </div>"""
+        You have three options:<br>
+        (1) Structure as is: perform a self consistent calculation using the structure provided as input.<br>
+        (2) Atomic positions: perform a full relaxation of the internal atomic coordinates. <br>
+        (3) Full geometry: perform a full relaxation for both the internal atomic coordinates and the cell vectors. </div>"""
     )
     materials_help = ipw.HTML(
         """<div style="line-height: 140%; padding-top: 10px; padding-bottom: 10px">
-        Below you can indicate both if the material is magnetic and a metal or insulator. For now only ferromagnetic configurations are possible, since antiferromagnetism is more complicated to study automatically. If you're not sure whether your material is insulating, choose "Metal", since the corresponding settings usually also work quite well for insulators.
+        Below you can indicate both if the material should be treated as an insulator
+        or a metal (if in doubt, choose "Metal"),
+        and if it should be studied with magnetization/spin polarization,
+        switch magnetism ON or OFF (ON is at least twice more costly).
         </div>"""
     )
 
@@ -76,10 +80,9 @@ class WorkChainSettings(ipw.VBox):
     )
     protocol_help = ipw.HTML(
         """<div style="line-height: 140%; padding-top: 6px; padding-bottom: 0px">
-        The "moderate" protocol represents a balanced trade-off between
+        The "moderate" protocol represents a trade-off between
         accuracy and speed. Choose the "fast" protocol for a faster calculation
-        with less precision and the "precise" protocol that provides more
-        accuracy but will take longer.</div>"""
+        with less precision and the "precise" protocol to aim at best accuracy (at the prece of longer/costlier calculations).</div>"""
     )
 
     def __init__(self, **kwargs):
@@ -139,8 +142,8 @@ def __init__(self, **kwargs):
                 self.structure_help,
                 self.relax_type,
                 self.materials_help,
-                self.spin_type,
                 self.electronic_type,
+                self.spin_type,
                 self.properties_title,
                 ipw.HTML("Select which properties to calculate:"),
                 ipw.HBox(children=[ipw.HTML("<b>Band structure</b>"), self.bands_run]),
@@ -165,7 +168,8 @@ class SmearingSettings(ipw.VBox):
     smearing_description = ipw.HTML(
         """<p>
         The smearing type and width is set by the chosen <b>protocol</b>.
-        Tick the box to override the default.
+        Tick the box to override the default, not advised unless you've mastered <b>smearing effects</b> (click <a href="http://theossrv1.epfl.ch/Main/ElectronicTemperature"
+        target="_blank">HERE</a> for a discussion).
     </p>"""
     )
 
@@ -236,11 +240,10 @@ def set_smearing(self, _=None):
 class KpointSettings(ipw.VBox):
 
     kpoints_distance_description = ipw.HTML(
-        """<p>
-        The k-points mesh density of the SCF calculation is set by the chosen <b>protocol</b>.
+        """<div>
+        The k-points mesh density of the SCF calculation is set by the <b>protocol</b>.
         The value below represents the maximum distance between the k-points in each direction of reciprocal space.
-        Tick the box to override the default.
-    </p>"""
+        Tick the box to override the default, smaller is more accurate and costly. </div>"""
     )
 
     # The default of `kpoints_distance` must be linked to the `protocol`

diff --git a/qe.ipynb b/qe.ipynb
@@ -93,7 +93,7 @@
     "app = WizardAppWidget(\n",
     "    steps=[\n",
     "        ('Select structure', structure_selection_step),\n",
-    "        ('Configure work chain', configure_qe_app_work_chain_step),\n",
+    "        ('Configure workflow', configure_qe_app_work_chain_step),\n",
     "        ('Choose computational resources', submit_qe_app_work_chain_step),\n",
     "        ('Status & Results', view_qe_app_work_chain_status_and_results_step),\n",
     "    ])\n",