Skip to content

Commit 7ce6ed7

Browse files
BTSpeakeBTSpeake
authored
Initial User Guide (#16)
1 parent 6c47080 commit 7ce6ed7

16 files changed

Lines changed: 512 additions & 28 deletions

‎docs/source/_static/custom.css‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
/* Fix figure styling */
2+
.centre-fig {
3+
display: blockl;
4+
margin-left: auto;
5+
margin-right: auto;
6+
text-align: center;
7+
font-style: italic;
8+
}

‎docs/source/conf.py‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -33,4 +33,5 @@
3333

3434
html_theme = 'piccolo_theme'
3535
html_static_path = ['_static']
36+
html_css_files = ["custom.css"]
3637
html_logo = "../../images/alc-100.webp"

‎docs/source/dev_docs/aiidalab_app_design.rst‎

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,22 @@
1+
Plugin Design
2+
=============
3+
4+
AiiDAlab plugins are designed as jupyter notebook UIs with a core package providing the
5+
UI components. Each plugin is required to have a ``setup.cfg`` and a ``start.py`` files
6+
within their root directory to specify to AiiDAlab the plugin metadata and how to display
7+
the start banner for the plugin. From here each page defined within the application is
8+
described by a jupyter notebook (\*.ipynb) file which may call components from the
9+
core python package.
10+
11+
Model-View-Controller Paradigm
12+
------------------------------
13+
14+
It is recommended that an AiiDAlab plugin follows the widely recognised Model-View-Controller
15+
design paradigm for UI development.
16+
The core UI package will use ``IPywidgets`` (or aiidalab's own pre-configured widgets) to display
17+
the various UI components that a user will interact with. This defines the *view* for the application.
18+
The data that is being handled should exist seperate to any visual components that are part
19+
of the applications *view* layer. They are handled by the ``traitlets`` python packages and can
20+
be dynamically linked to user inputs through the *view* layer but should exist indendantly, thus
21+
defining the *model* layer. The controller layer is an optional additional layer that defines user
22+
controll over that application that doesn't directly interact with any of the stored data.

‎docs/source/dev_docs/containers.rst‎

Lines changed: 85 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,85 @@
1+
Developing With Docker Containers
2+
=================================
3+
4+
Developing Within a Container
5+
-----------------------------
6+
7+
AiiDAlab is setup to run efficiently within a containerised server hosting the core
8+
jupyter notebook and AiiDAlab plugins. AiiDAlab host several docker images which can
9+
be used for development of AiiDAlab applications. The most useful of which is the
10+
AiiDAlab/full-stack image which will start an instance of the base AiiDAlab home
11+
page without installing any additional applications. To use this container you can
12+
run the following,
13+
14+
.. code:: bash
15+
16+
# Docker
17+
docker run -it --rm -p 8888:8888 aiidalab/full-stack:latest
18+
# Apptainer
19+
apptainer run --compat --cleanenv --home /home/jovyan docker://aiidalab/full-stack:latest
20+
21+
To enable an AiiDAlab application within the container it must be installed in the
22+
``/home/jovyan/apps/`` directory. This can be achieved by either installing using the
23+
in build terminal page or via binding a local instance of the development code into the
24+
container at initialisation,
25+
26+
.. code:: bash
27+
28+
# Docker
29+
docker run -it --rm -p 8888:8888 -v /path/to/myApp:/home/jovyan/apps/myApp aiidalab/full-stack:latest
30+
# Apptainer
31+
apptainer run --compat --cleanenv --home /home/jovyan --bind /path/to/myApp:/home/jovyan/apps/myApp docker://aiidalab/full-stack:latest
32+
33+
Python Limitations
34+
------------------
35+
36+
A known current limitation of the provided AiiDAlab docker images is there python version
37+
is capped at 3.9 which can cause compatability issues with more up-to-data python packages.
38+
A custom docker image is provided in this repository which will mimic the aiidalab.full-stack
39+
image but using 3.10 as the base python version. This can be accessed at
40+
`<ghcr.io/stfc/alc-ux/base:latest>`_ and used as described above.
41+
42+
Docker Images For Distribution
43+
------------------------------
44+
45+
Whilst it is possible to use the base images by installing plugins at runtime, it is often useful
46+
to generate a custom docker image which contains all the required components and plugins for a
47+
given workflow out of the box. This can be achieved by bulding upon the base images described above.
48+
An example of this is the ``aiidalab/qe`` image which contains a pre-installed Quantum ESPRESSO plugin
49+
and all its dependencies. To create a custom image you will need to create a ``Dockerfile`` which uses
50+
the disired base image, then install all required dependencies and ensure that the AiiDAlab plugins are
51+
installed in the ``/home/jovyan/apps/`` directory so they are discoverable by the AiiDAlab runtime.
52+
53+
.. code:: dockerfile
54+
55+
FROM aiidalab/full-stack:latest
56+
57+
USER root
58+
59+
# Install some extra required dendencies to speed up start up
60+
RUN pip install aiidalab_widgets_base --no-cache-dir --no-user
61+
62+
# Install any required aiida plugins
63+
RUN pip install aiida-chemshell aiida-mlip --no-cache-dir --no-user
64+
65+
# This will install alc-ux AiiDAlab app on container start up into the correct directory
66+
COPY 61_prepare-aiidalab_alc.sh /usr/local/bin/before-notebook.d/
67+
68+
USER ${NB_UID}
69+
WORKDIR ${HOME}
70+
71+
where the initialisation script ``61_prepare-aiidalab_alc.sh`` contains the following,
72+
73+
.. code:: bash
74+
75+
#!/bin/bash
76+
77+
echo "INSTALLING AiiDAlab ALC app"
78+
cd "${HOME}"/apps
79+
wget https://github.com/stfc/alc-ux/archive/refs/heads/main.zip
80+
unzip main.zip
81+
rm -f main.zip
82+
cd "${HOME}"/apps/alc-ux-main
83+
pip install -q .
84+
85+
cd "${HOME}"

‎docs/source/dev_docs/index.rst‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
Developer Guide
2+
===============
3+
4+
Welcome to the ALC AiiDAlab app's developer guide.
5+
6+
.. toctree::
7+
:maxdepth: 2
8+
9+
intro
10+
containers
11+
aiidalab_app_design

‎docs/source/dev_docs/intro.rst‎

Lines changed: 96 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,6 @@
11
Getting Started
22
===============
33

4-
Welcome to the ALC AiiDAlab app's developer guide.
5-
64

75
Running The Test Suite
86
----------------------
@@ -39,6 +37,101 @@ or any new modules can be added manually. All docstrings are to be written in `n
3937
Coding Style
4038
------------
4139

40+
This project adheres to the `pep8 <https://peps.python.org/pep-0008/>`_ style guide for python coding alongside numpy style docstring formatting. This should be checked before any code updates. A pre-commit configuration using the ruff linter tool is provided for convenience.
41+
4242

4343
Contributing
44-
------------
44+
------------
45+
46+
Contributing Workflow
47+
~~~~~~~~~~~~~~~~~~~~~
48+
49+
This document outlies the best practices for contributing to the ALC-ux project. These must be
50+
followed for any contributions to be accepted. In brief the contribution process should be as
51+
follows:
52+
53+
- Follow the branch, fix, merge model, from your own fork or fork/branch model.
54+
- Create an issue for all work (bug, feature etc.)
55+
- Pull requests will not be accepted without review.
56+
- Any new feature must include appropriate testing.
57+
58+
Using git for development
59+
~~~~~~~~~~~~~~~~~~~~~~~~~
60+
61+
The core *upstream* repository is hosted on GitHub which contributors will create forks, from
62+
using the GitHub web UI, to carry out any development work. This maintains a clean core repository.
63+
Once a fork has been created the branch, fix, merge workflow should be followed.
64+
65+
**Step 1: Branch**
66+
67+
68+
Create a new branch for the issue with an appropriate name (e.g. issueXYZ). This can either
69+
be carried out through the web UI, then cloned using,
70+
71+
.. code:: bash
72+
73+
git clone -b issueXYZ --single-branch git@github.com:username/alc-ux.git
74+
75+
76+
Alternatively, use the CLI directly to create and checkout the new branch,
77+
78+
.. code:: bash
79+
80+
# clone the repository
81+
git clone git@github.com:username/alc-ux.git
82+
# create and checkout a new branch
83+
git checkout -b issueXYZ
84+
# create a remote tracking branch
85+
git push -u origin issueXYZ
86+
87+
88+
**Step 2: Fix**
89+
90+
91+
Here you will fix the issue commit all changes to the new remote tracking branch within
92+
your fork, ensuring all style guidelines are followed and changes are appropriately
93+
documented.
94+
95+
**Step 3: Merge**
96+
97+
98+
Via the web UI, create a pull request from your development branch into the upstream
99+
repository. Include any relevant labels or milestones and assign a reviewer. Once the
100+
request has been created, tests will be run and the review process will begin, which may
101+
include discussions using the comment system on the pull request. If changes need to be
102+
made you may make more commits onto your development branch which will be added to the
103+
pull request automatically. Once all is OK with the commit then the reviewer will set
104+
the request to be merged once all tests have passed.
105+
106+
If your branch has become out of sync with the *upstream* repository then conflicts
107+
may arise. If they cannot be resolved automatically by git you will need to resolve them
108+
by hand as detailed in the GitHub documentation.
109+
110+
It is best practice that when you submit the pull request you squash your commits into
111+
a single commit that will be applied to the *upstream* repository. This is enabled by
112+
default and should not be switched off.
113+
114+
**Cleaning stale branches**
115+
116+
117+
Deleting branches from the web interface will get rid of the remotes and
118+
not of your local copies. The local branches left behind are called
119+
stale branches. To get rid of them
120+
121+
.. code:: bash
122+
123+
git remote prune origin
124+
125+
126+
To delete a local branch
127+
128+
.. code:: bash
129+
130+
git branch -d localBranch
131+
132+
133+
if unmerged commits exists but you still want to delete use
134+
135+
.. code:: bash
136+
137+
git branch -D localBranch

‎docs/source/index.rst‎

Lines changed: 10 additions & 22 deletions
Original file line numberDiff line numberDiff line change
@@ -1,29 +1,17 @@
1+
.. figure:: ../../images/alc.svg
2+
:alt: ALC Logo
3+
:width: 70%
4+
:align: center
5+
:figclass: centre-fig
6+
17
ALC AiiDAlab App
28
================
39

4-
5-
User Guide
6-
----------
7-
8-
.. toctree::
9-
:maxdepth: 2
10-
11-
user_docs/intro
12-
13-
14-
Developer Guide
15-
---------------
16-
1710
.. toctree::
18-
:maxdepth: 2
19-
20-
dev_docs/intro
11+
:maxdepth: 2
2112

22-
API Documentation
23-
-----------------
24-
25-
.. toctree::
26-
:maxdepth: 3
27-
13+
user_docs/index
14+
dev_docs/index
2815
api_docs/modules
2916

17+

‎docs/source/user_docs/ada_guide.rst‎

Lines changed: 68 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,68 @@
1+
.. _cloud_deployment_guide:
2+
3+
Deployment on ADA Cloud Workspace
4+
=================================
5+
6+
This guide details how to use AiiDAlab and the AiiDAlab ALC application on a cloud based
7+
remote workstation using the UKRI's `ADA <https://ada.stfc.ac.uk/>`_ service as an example.
8+
The information provided here can be easily generalised to any remote/cloud based workstation
9+
that utilises `Apptainer <https://apptainer.org/docs/user/main/index.html>`_ contained
10+
applications.
11+
12+
Setup ADA Workspace
13+
-------------------
14+
15+
Run AiiDAlab
16+
------------
17+
18+
ADA uses Apptainer for container deployment which can in turn pull and run the docker
19+
image's provided with the AiiDAlab ALC app. Since these images were created to be used
20+
with docker a few key settings must be passed to ensure correct behaviour within the
21+
container. First are the ``--compat`` and ``--cleanenv`` parameters which prevent
22+
mounting of any local system filespaces or environment variables which could interfere
23+
with the container. This provides a more docker like approach to running containers,
24+
however, it is still required that the home directory be mounted to the container so
25+
that work will persist between instances of AiiDAlab. This is achieved by mounting the
26+
users home directory to the container's home directory which exists at ``/home/jovyan``
27+
and then setting the home parameter to this directory. The full commands are shown below.
28+
29+
To run a basic AiiDAlab instance running on python 3.10, with no installed additional
30+
applications besides the core AiiDAlab home interface run the following command from a
31+
terminal instance on the virtual workspace,
32+
33+
.. code:: bash
34+
35+
apptainer run --compat --cleanenv --bind ${HOME}:/home/jovyan --home /home/jovyan docker://ghcr.io/stfc/alc-ux/base:latest
36+
37+
To run an AiiDAlab instance which contains the AiiDAlab ALC application and some additional
38+
required python libraries, instead run,
39+
40+
.. code:: bash
41+
42+
apptainer run --compat --cleanenv --bind ${HOME}:/home/jovyan --home /home/jovyan docker://ghcr.io/stfc/alc-ux/full:latest
43+
44+
In addition to these supplied images, any of the official
45+
`AiiDAlab docker images <https://github.com/aiidalab/aiidalab-docker-stack>`_ can be
46+
used in the same manner, however, at present these are limited to python 3.9 which limits
47+
support with certain core AiiDA plugin's provided by the ALC.
48+
49+
Data Persistence Within the Workspace
50+
-------------------------------------
51+
52+
If these images have been run ensuring correct mounting of the user's home directory,
53+
then all data produced and managed by AiiDA/AiiDAlab will persist between instances
54+
of the AiiDAlab container. The first time the container is run, all required data
55+
directories for AiiDA will be produced in the user's home directory. This includes
56+
the ``.aiida`` directory containing the profile information for AiiDA and the
57+
``.postgresql`` directory which contains the database information. Whilst these
58+
exist the container will read any profile or database information from them
59+
instead of initialising new instances on start up. Additionally any files/folders
60+
generated from within the container or AiiDAlab application will persist as long
61+
as they exist within the mounted home space.
62+
63+
Data Persistence Outside the Workspace
64+
--------------------------------------
65+
66+
It is recommended to use AiiDA's data base exporting tools to save the generated database with all
67+
results and provenance relations. This can then be imported into another instance of AiiDA to view
68+
or use any of the data nodes within the database.

‎docs/source/user_docs/index.rst‎

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
User Guide
2+
----------
3+
4+
Welcome to the ALC AiiDAlab app's user guide. This documentation is designed to help you get started with using the app effectively.
5+
Whether you're new to AiiDAlab or looking to enhance your workflow, you'll find valuable information here.
6+
7+
.. toctree::
8+
:maxdepth: 2
9+
10+
intro
11+
run_local
12+
ada_guide
13+
resource_manager

0 commit comments

Comments
 (0)