add 'limitations' section to intro

[ltalirz]

I think the introduction of aiida-shell is clear and easy to follow. It would be even better, if before the "How to cite" section you would add a brief section on limitations with a bullet point of tasks where people should look elsewhere

E.g.

• I understand you cannot use aiida_shell to run on remote computers (?)
• Running via mpi might be possible via parameters but I guess it is not natively supported (?)
• ...

P.S. I like the logo, but "SiiEll" is weird to me (are people supposed to pronounce that?).

[sphuber]

Thanks for the feedback @ltalirz . I agree such a section would be useful if we can find limitations that would be relevant to users.

I understand you cannot use aiida_shell to run on remote computers (?)

This is supported. You can configure a remote computer as you would do normally in AiiDA and either directly specify a Code instead of the command string, or you can even specify the computer directly in metadata.options.computer without having to manually create the Code instance.

Running via mpi might be possible via parameters but I guess it is not natively supported (?)

This is also supported. Since you can specify a Computer, either directly in metadata.options.computer or indirectly via the Code input, if that is configured to run with MPI that will run as a normal calcjob in AiiDA. You can also configure any other MPI related options through metadata.options as with any other CalcJob, for example the mpirun_extra_params and withmpi options. There is not a concrete how-to section for this though. I could try and think of an example and add one.

So far I am not actually aware of any limitations. It is even possible to define custom parsers on-the-fly and they can be submitted to the daemon without having to create entry points or doing tricks with imports. This is what I think make aiida-shell so flexible and easy to get started with.

I guess the one limitation is that at some point, if you want to start to flesh out a more complex interface to a particular code, or the parsers become quite involved, it may start to make sense to actually write dedicated plugins instead. Those still have a time and place for sure.

Of course if you find any other limitations I would be happy to add the section you suggested. Or maybe I can start already with the small paragraph above suggesting when it might be better to switch to using dedicated plugins? But I thought this might be a bit much information for an introductory page.

P.S. I like the logo, but "SiiEll" is weird to me (are people supposed to pronounce that?).

It is simply a stylized version of "SHELL" where the H is made to look like the double ii in AiiDA. I did this for stylistic reasons as I think the symmetry looks kind of cool :D I agree that it may not appear obvious in the beginning but I think as with time aiida-shell will become more known, people will grok it

[ltalirz]

Hey Seb, thanks for the follow-up!

Concerning MPI support: that's great! Perhaps it would be worth adding a short example in the howto section in order to clarify that you can use aiida shell for parallel calculations as well.

As far as running on a remote computer, is the user then responsible for transferring the input files to the remote computer or does aiida shell handle this? The question that brought me to the docs was: for a simple code that takes one input file (but should run on a HPC machine, not just a little script on my computer) does it make sense to direct a code developer to start with aiida shell or do they have to write a CalcJob plugin?

In the howto section I came across the RemoteData example, which seemed to imply that the user is responsible for transferring data. If that is the case, then running on a remote computer may be technically supported, but not practical (it's too complicated).

[sphuber]

Concerning MPI support: that's great! Perhaps it would be worth adding a short example in the howto section.

Will look into adding a how-to soonish.

As far as running on a remote computer, is the user then responsible for transferring the input files to the remote computer or does aiida shell handle this?

Nope, aiida-shell does all the file transfers automatically.

The question that brought me to the docs was: for a simple code that takes one input file (but should run on a HPC machine, not just a little script on my computer) does it make sense to direct a code developer to start with aiida shell or do they have to write a CalcJob plugin?

If it is a simple program that takes a single file, aiida-shell sounds like a great candidate. All they have to do is configure the remote computer and then run:

from aiida.orm import load_computer
from aiida_shell import launch_shell_job
launch_shell_job(
    'the-executable-name',
    arguments='--some-flag {input_file}',
    nodes={
        'input_file': '/local/path/to/file',  # This will automatically be converted to `SinglefileData` or you can provide that yourself directly
    },
    metadata={
        'options': {
            'computer': load_computer('remote-computer')
        }
    }
)

You can simply provide the input file in the inputs, assuming that file exists on the machine from where you are submitting, and aiida-shell will copy it to the work directory.

In the howto section I came across the RemoteData example, which seemed to imply that the user is responsible for transferring data. If that is the case, then running on a remote computer may be technically supported, but not practical (it's too complicated).

This is only for use-cases where you already have some data on the computer where you want to run and that needs to be copied to the working directory of the command you want to run. By passing this directory as a RemoteData you can have aiida-shell take care of the transfer. But this is a specific use-case. Or for example when you already ran a job through aiida-shell on a remote and now you want to use its results in a second job on the same machine. You can use the RemoteData of the first job (i.e. the remote_folder outptut) to automatically take care of file transfer.

[ltalirz]

Ah great!

It will definitely be worth to create a section on how this. Eg we could add a section on how to run lammps that can really have just one input file.

[sphuber]

All the parts necessary to run this are already in the how-to guides. I think what might be missing are some concrete examples, because now people will have to read all the how-tos to figure things out and cobble it together. I am thinking of making a separate page in the docs with complete examples of real life use-cases, such as running LAMMPS. This will hopefully be a good entry point for people to envision how they can translate it to their specific code.

[ltalirz]

A cookbook page like this sounds like a great idea

[sphuber]

@ltalirz I added a section of hands-on examples: https://aiida-shell.readthedocs.io/en/latest/examples.html The Quantum ESPRESSO based example includes a section on enabling and configuring MPI: https://aiida-shell.readthedocs.io/en/latest/examples/qe.html#running-with-mpi

[ltalirz]

Thanks a lot, Seb, these examples are great!