Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

providing a subsection in developer guide docs, about automatic code installation #576

Open
wants to merge 2 commits into
base: main
Choose a base branch
from
Open
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
80 changes: 79 additions & 1 deletion docs/source/development/plugin.rst
Original file line number Diff line number Diff line change
Expand Up @@ -354,11 +354,89 @@ Here is the example of the built-in `pdos` plugins with codes `dos.x` and `projw
}

For the moment, the app does not support set up the newly added codes automatically.
Thus, the user needs to set up the codes manually.
Thus, the user needs to set up the codes manually. However, the developer can provide console
scripts to make user life easier. Please read to following section for some instructions on how
to do it.
Comment on lines +357 to +359
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We try to break lines for a full sentence to make it easy to review and for future change. Do need to worry about a long line (if it is super long, then probably means it can be cut to short sentences for readability).



Setting up console scripts for automatic code installation
----------------------------------------------------------
It is possible to provide console scripts in order to make new code installation almost automatic,
with only running an instruction from the command line.
Comment on lines +364 to +365
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
It is possible to provide console scripts in order to make new code installation almost automatic,
with only running an instruction from the command line.
It is possible to provide console scripts to make new code installation almost automatic, by only running an instruction from the command line.

Console scripts can be defined in the `pyproject.toml`:

.. code-block::

[project.scripts]
phonopy_install = "phonopy_install:install_phonopy"

When the user, after the package installation, will execute the command

.. code-block:: console

phonopy_install

this will invoke the function `install_phonopy`, contained in the phonopy_install.py file in the
root directory of the package.
Comment on lines +379 to +380
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
this will invoke the function `install_phonopy`, contained in the phonopy_install.py file in the
root directory of the package.
this will invoke the function `install_phonopy`, contained in the `phonopy_install.py` file in the root directory of the package.


or in the `setup.cfg` file (if you prefer):
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
or in the `setup.cfg` file (if you prefer):
Another option is add following lines in the `setup.cfg` file:


.. code-block::

[options.entry_points]
console_scripts=
install_muon_codes = aiidalab_qe_muon.scripts.post_install:InstallCodes

this will invoke the function `InstallCodes`, contained in the post_install.py file in the
{root-directory-of-the-package}/aiidalab_qe_muon/scripts/ directory.
Comment on lines +390 to +391
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
this will invoke the function `InstallCodes`, contained in the post_install.py file in the
{root-directory-of-the-package}/aiidalab_qe_muon/scripts/ directory.
This will invoke the function `InstallCodes`, contained in the `post_install.py` file in the `<root-directory-of-the-package>/aiidalab_qe_muon/scripts/` directory.


These examples are taken respectively from `aiidalab-qe-vibroscopy`_ and `aiidalab-qe-muon`_.
The actual function to install the code should be something similar:

.. code-block:: python

from aiida.common.exceptions import NotExistent
import subprocess
from aiida.orm import load_code
from aiida import load_profile

def install_phonopy():
load_profile()
try:
load_code("phonopy@localhost")
except NotExistent:
# Construct the command as a list of arguments
command = [
"verdi",
"code",
"create",
"core.code.installed",
"--non-interactive",
"--label",
"phonopy",
"--default-calc-job-plugin",
"phonopy.phonopy",
"--computer",
"localhost",
"--filepath-executable",
"/opt/conda/bin/phonopy",
]

# Use subprocess.run to run the command
subprocess.run(command, check=True)
else:
raise Warning("Code phonopy@localhost already installed!")


# Called when the script is run directly
if __name__ == "__main__":
install_phonopy()

Further Reading
================================
QuantumESPRESSO app comes with several built-in plugins, which can be found in the ``aiidalab_qe.plugins`` folder.
You can also use them as a start point to create your own plugins.

.. _aiidalab-qe-plugin-demos: https://github.com/aiidalab/aiidalab-qe-plugin-demos
.. _aiidalab-qe-vibroscopy: https://github.com/mikibonacci/aiidalab-qe-vibroscopy
.. _aiidalab-qe-muon: https://github.com/mikibonacci/aiidalab-qe-muon