Skip to content

Commit 55fe31a

Browse files
edan-bainglassedan-bainglass
committed
Update docs
1 parent e62506a commit 55fe31a

File tree

1 file changed

+245
-17
lines changed

1 file changed

+245
-17
lines changed

‎docs/source/development/architecture.rst‎

Lines changed: 245 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -12,21 +12,243 @@ Each step may contain several sections (panels), as shown in the figure below.
1212

1313
.. image:: ../_static/images/plugin_step.png
1414

15-
Parameter transfer between steps
16-
---------------------------------
15+
MVC design
16+
==========
1717

18-
The data is passed to the next step by linking it to the corresponding ``trait`` of the step widget.
19-
For example, the ``confirmed_structure`` of step 1 links to the ``input_structure`` trait of step 2.
18+
The app is designed following a Model-View-Controller (MVC) pattern, with data managed solely by the model network (the source of truth).
19+
20+
A simple model may look like the following:
21+
22+
.. code:: python
23+
24+
class SimpleModel(tl.HasTraits):
25+
26+
# Define traits
27+
trait = tl.Unicode("I am a trait") # `tl` is alias for `traitlets`
28+
...
29+
30+
def __init__(self, *args, **kwargs): # Optional, only if required
31+
super().__init__(*args, **kwargs)
32+
33+
# Optional attributes can be defined here
34+
35+
def reset(self):
36+
# Reset the model to its defaults
37+
38+
The corresponding View-Controller may look like this:
39+
40+
.. code:: python
41+
42+
class SimpleWidget(ipw.VBox):
43+
def __init__(self, model=SimpleModel, **kwargs):
44+
from aiidalab_qe.common.widgets import LoadingWidget
45+
46+
super().__init__(
47+
children=[LoadingWidget("Loading message")], # loading spinner icon
48+
**kwargs,
49+
)
50+
51+
self._model = model
52+
53+
# Contoller observations of model changes
54+
self._model.observe(
55+
self._on_trait_change,
56+
"trait",
57+
)
58+
...
59+
60+
# View
61+
def render(self):
62+
if self.rendered:
63+
return
64+
65+
# Define and link widgets
66+
widget = ipw.Dropdown(description="Trait")
67+
ipw.dlink(
68+
(self._model, "options"),
69+
(widget, "value"),
70+
)
71+
ipw.link(
72+
(self._model, "trait"),
73+
(widget, "value"),
74+
)
75+
ipw.dlink(
76+
(self._model, "override"),
77+
(widget, "disabled"),
78+
lambda override: not override,
79+
)
80+
...
81+
82+
self.children = [
83+
widget,
84+
...
85+
]
86+
87+
self.rendered = True
88+
89+
# Controller methods
90+
# EXAMPLE
91+
def _on_trait_change(self, change):
92+
# Update widgets based on model changes
93+
...
94+
95+
MVC in the configuration step
96+
-----------------------------
97+
98+
Some models require additional functionality, particularly in the configuration step (step 2), where many MVC components come together to form the
99+
UI for specifying both the workflow and its input.
100+
Each of these is defined as a ``SettingsPanel`` with a corresponding ``SettingsModel``.
101+
Some of these are defined in the app, such as the basic and advanced settings panels.
102+
For dedicated calculations (e.g. bands, pdos, xps), they are defined externally as :ref:`plugins <develop:plugins>`.
103+
104+
Below are snippets of the ``AdvancedModel`` and ``AdvancedSettings`` classes:
105+
106+
.. code:: python
107+
108+
class AdvancedModel(
109+
SettingsModel,
110+
HasModels[AdvancedSubModel],
111+
HasInputStructure,
112+
):
113+
dependencies = [
114+
"input_structure",
115+
"workchain.protocol",
116+
...
117+
]
118+
119+
protocol = tl.Unicode()
120+
121+
kpoints_distance = tl.Float(0.0)
122+
...
123+
124+
self.include = True # includes this model in the configuration step
125+
126+
# Optional attributes can be defined here
127+
self.dftd3_version = {
128+
...
129+
}
130+
131+
def update(self, specific=""):
132+
# Update the model, optionally limited to a specific scope
133+
...
134+
135+
def get_model_state(self) -> dict:
136+
# Return the model state as a dictionary
137+
...
138+
139+
def set_model_state(self, parameters: dict):
140+
# Set the model state from a parameters dictionary
141+
# Used when loading a previous calculation
142+
...
143+
144+
def reset(self):
145+
# Reset the model to its defaults
146+
...
147+
148+
Model updates recompute trait defaults w.r.t dependent traits (e.g. input structure, protocol) and update the model's traits to these defaults.
149+
The defaults are stored in a ``_defaults`` dictionary that is used in ``reset`` to return the model to its *current* defaults.
150+
The dependencies of a model are defined in the ``dependencies`` list, which is used by in configuration step during plugin discovery to connect the model network.
151+
The inter-connection of dependency traits forms an **Observer** pattern across the app, with each dependent model receiving notifications of state changes in dependencies.
152+
When a calculation is submitted, the configuration step will collect the parameters from all *included* models (``include == True``) and pass them to the submit step.
153+
154+
.. note:: The basic and advanced models are included by default. Inclusion of installed plugin models is controlled by the user in step 2.1.
155+
156+
.. warning:: The ``default_value`` of ``List`` or ``Dict`` traits is not stored by ``traitlets``.
157+
Instead, explicitly define the defaults to at least ``[]`` or ``{}``, respectively.
158+
159+
.. code:: python
160+
161+
class AdvancedSettings(SettingsPanel[AdvancedModel]):
162+
title = "Advanced Settings"
163+
identifier = "advanced"
164+
165+
def __init__(self, model: AdvancedModel, **kwargs):
166+
super().__init__(
167+
model=model,
168+
layout={"justify_content": "space-between", **kwargs.get("layout", {})},
169+
**kwargs,
170+
)
171+
172+
self._model.observe(
173+
self._on_input_structure_change,
174+
"input_structure",
175+
)
176+
...
177+
178+
# Optionally connect sub-MVC components
179+
smearing_model = SmearingModel()
180+
self.smearing = SmearingSettings(model=smearing_model)
181+
model.add_model("smearing", smearing_model)
182+
...
183+
184+
def render(self):
185+
if self.rendered:
186+
return
187+
188+
# Define and link widgets
189+
...
190+
191+
self.children = [
192+
...
193+
]
194+
195+
self.rendered = True
196+
197+
.. note:: The generic type ``AdvancedModel`` in ``SettingsPanel[AdvancedModel]`` is used to specify the model type, which is used to infer the type of the model in the class and provide type hinting in modern IDEs.
198+
199+
Mixins
200+
------
201+
202+
The ``HasModels`` mixin class inherited by the ``AdvancedModel`` is used to manage sub-models.
203+
It provides functionality to add, register, and get a sub-model.
204+
It is presently used by the configuration step to register basic, advanced, and plugin models.
205+
It is also used by the advanced panel to register the sub-sections of the advanced settings (e.g. magnetization, hubbard, etc.).
206+
207+
Other mixins, such as ``HasInputStructure``, provide are trait oriented, providing both the trait and methods to work with it.
208+
The ``Confirmable`` mixin, for example, provides a ``confirmed`` trait, a ``confirm`` method, and an means of un-confirming on any state change in the inheriting model.
209+
210+
.. code:: python
211+
212+
class Confirmable(tl.HasTraits):
213+
confirmed = tl.Bool(False)
214+
215+
def confirm(self):
216+
self.confirmed = True
217+
218+
@tl.observe(tl.All)
219+
def _on_any_change(self, change):
220+
if change and change["name"] != "confirmed":
221+
self._unconfirm()
222+
223+
def _unconfirm(self):
224+
self.confirmed = False
225+
226+
App status
227+
==========
228+
229+
To keep track of the status of the app at any given step, a ``state`` trait of a step is linked with the ``previous_step_state`` trait of its following step. A ``SUCCESS`` state is used to auto-proceed to a following step.
230+
The ``state`` trait is updated on most events.
20231

21232
.. code:: python
22233
23234
ipw.dlink(
24-
(self.structure_selection_step, "confirmed_structure"),
25-
(self.configure_qe_app_work_chain_step, "input_structure"),
26-
)
235+
(self.structure_step, "state"),
236+
(self.configure_step, "previous_step_state"),
237+
)
238+
239+
Data management across steps
240+
============================
241+
242+
Data is passed to the next step by use of ``App``-level controller observations of step (un)confirmation following the **Mediator** pattern, as follows:
243+
244+
- Step 1 confirmed -> triggers setting of ``input_structure`` in step 2
245+
- Step 2 confirmed -> triggers setting of ``input_structure`` and ``input_parameters`` in step 3
246+
- Step 3 submitted -> triggers setting of ``process.uuid`` in step 4
27247

28-
Each step widget can contains several panels. In the configuration step, the parameters from the panels are generated and stored as a dictionary, which is linked to the ``input_parameters`` trait of the next submit step.
29-
The dictionary has the following structure:
248+
.. note:: In the observers of step 1 and 2, ``_update_blockers()`` is also triggered to identify any current blockers to submission.
249+
These blockers are linked with the submission model, which is used to show any submission warnings in step 3.
250+
251+
In confirming step 2, the configuration step collects the parameters from all included models and returns them as a dictionary of the following format:
30252

31253
.. code:: python
32254
@@ -55,17 +277,23 @@ The dictionary has the following structure:
55277
"plugin_2": {...},
56278
}
57279
58-
Plugin
59-
=========
60-
QuantumESPRESSO app supports running multiple properties (bands, pdos, etc.) calculations in one app.
61-
The individual properties to be developed and seamlessly integrated into the QuantumESPRESSO app as plugins. This integration is made possible due to several key aspects:
280+
.. _develop:plugins:
281+
282+
Plugins
283+
=======
62284

63-
- the configuration for a property calculation has its settings unrelated to other properties.
64-
- the sub-workchain of the properties can be run independently.
65-
- the analysis of the results of the properties is independent.
285+
The Quantum ESPRESSO app supports computing multiple properties (bands, pdos, etc.).
286+
For this, plugins are to be developed and seamlessly integrated into the app.
287+
The integration is made possible by several key aspects:
66288

67-
Each plugin responsible for one property calculation.
289+
- The configuration settings for a property calculation must be decoupled from any other plugin - no cross-dependency
290+
- The sub-workchain of a property can be run independently
291+
- The analysis of the results of a property is independent
292+
293+
Each plugin is responsible for the calculation of a single property.
68294
For instance, we could create a PDOS plugin, including its settings, workchain, and result analysis.
295+
296+
.. TODO modify below
69297
The GUI of the PDOS plugin is only loaded when the user selects to run it.
70298
Here is an example, where two new setting panels are shown when the user selects to run the properties.
71299

0 commit comments

Comments
 (0)