Running ESPResSo in the web browser

[Jean-Noël Grad]

Dear users,

The ESPResSo team is pleased to announce that two cloud-based solutions 
were developed to make the software more accessible. ESPResSo now runs 
directly in the web browser, in a single click, for free.

Binder gives you access to a Jupyter Notebook environment that runs 
tutorials out-of-the-box with ESPResSo 4.2.0 [2]. Gitpod gives you 
access to a web IDE and a terminal that automatically builds ESPResSo 
from the python branch [3].

Please find below detailed instructions on how to use these services. 
Feel free to contact us on the mailing list or on the GitHub Discussions 
if you need more information or have suggestions for improvement.

Best regards,
Jean-Noël Grad
Institute for Computational Physics
University of Stuttgart, Germany


Running a Gitpod instance
-------------------------

The Gitpod platform offers a free plan limited to 1 core per workspace 
and 50 core hours per month [4]. This cloud service requires a user 
account. The python branch of ESPResSo provides a YAML file to 
automatically build ESPResSo in the default configuration. Here is the 
direct link:

https://gitpod.io/#https://github.com/espressomd/espresso

The workspace automatically pulls dependencies and builds the source 
code. This usually takes 15 min. Once the build has completed, use the 
terminal to run simulation scripts:

```sh
$ ./pypresso ../samples/p3m.py
```

or start a JupyterLab session:

```sh
$ cd ${GITPOD_REPO_ROOT}/build/doc/tutorials
$ ../../ipypresso lab --NotebookApp.allow_origin="$(gp url 8888)" \
    --port=8888 --no-browser
```

In the bottom-right corner of the IDE, a notification will appear in a 
box to mention port 8888 is now active. Click the orange button "Make 
public" to open that port and then Ctrl+click one of the urls in the 
terminal output to open JupyterLab in a pop-up window. Some web browsers 
may block the pop-up and ask you to confirm opening an url that starts 
with `https://8888-espressomd-espresso-`, if that's the case, click on 
"Allow" to open JupyterLab in a new browser tab.

JupyterLab is the preferred way to run tutorials in Gitpod. Although 
tutorials can be executed in the IDE directly too, it requires the 
pypresso kernel, which is not visible the first time the IDE starts. To 
make it available, quit the Gitpod workspace by closing the tab in your 
web browser, then open the url again and select the old workspace. The 
pypresso kernel should now be available in the VS Code Jupyter 
environment. More details can be found in the user guide [6].

It is also possible to access a Gitpod workspace via SSH from any 
operating system [7].

Running a Binder instance
-------------------------

The Binder platform offers free spot instances limited to 1 core and 2 
GB of RAM. No user account is needed. Here is the direct link:

https://mybinder.org/v2/gh/jngrad/espresso-binder/HEAD

The workspace automatically pulls a Docker image containing a pre-built 
version of ESPResSo 4.2.0 in its default configuration, and then pip 
installs its python dependencies. This usually takes less than 4 min. In 
the main Launcher window, you can open a terminal to run simulation 
scripts:

```sh
$ python samples/p3m.py
```

Note how `python` is used instead of `pypresso`. To run tutorials, 
navigate to the `tutorials/exercises` folder and open one of the 
notebooks. The solutions are hidden but can be revealed by clicking on 
the "Show solutions" buttons. The other folder `tutorials/solutions` 
contains the same notebooks with the solutions already copy-pasted in 
the code cells.

If the JupyterLab interface is too confusing, it is possible to switch 
to the classic Jupyter Notebook interface by clicking on the `Help` tab 
and then on the `Launch Classic Notebook` item.

To share your session with a coworker, open a python terminal in the 
JupyterLab environment and run the following code to print the url and 
session token:

```python
import subprocess
out = subprocess.run(["jupyter", "notebook", "list"], 
capture_output=True)
url = out.stdout.decode("utf-8").split("\n")[1].split()[0]
url = url.replace("http://0.0.0.0:8888/";, "https://hub.mybinder.org/";)
print(url)
```

Users who open this link will be able to see and edit your files, but 
editing the same file at the same time won't work properly, because the 
file won't synchronize in real time. Live collaborative editing is 
therefore not possible yet, although a solution is currently being 
developed by the Jupyter Project [8]; if you have experience setting up 
this feature, we would welcome your input (the ESPResSo Binder git 
repository is available at [5]). People who use your link should leave 
your session with `File / Log Out`, and not with `File / Shut Down`, 
otherwise your session will be terminated too.

Motivation
----------

Running the last two ESPResSo summer schools as hybrid events helped us 
reach out to a wider audience who could not necessarily make travel 
arrangements to Europe. By providing recordings of the summer school 
lectures on YouTube [9] and making the hands-on sessions run in web 
browsers, we want to give everyone a chance to learn ESPResSo at their 
own pace, all year round.

Another application for these could services is the creation of 
reproducible execution environments that can be shared with your peers 
[10]. By storing simulation scripts together with a list of versioned 
dependencies in a git repository or on Zenodo, anyone can reproduce your 
scientific results in a web browser in a single click.

Remote research code execution in Jupyter environments is well 
established in academia, both for teaching and scientific research. We 
developed these two cloud-based solutions to satisfy slightly different 
needs: Gitpod is better suited to developers thanks to its IDE and git 
integration, while Binder is more suitable in a learning environment, 
since it provides a simpler interface and doesn't require subscription 
to online services.

How to help
-----------

Spread the word. This mailing list reaches people who are already 
comfortable building ESPResSo. If you know coworkers or students who 
would benefit from ESPResSo but had a bad experience installing the 
software, consider sharing this e-mail with them.

Tinker with the tools. The Gitpod [11] and Binder [5] configuration 
files are available online and are easy to adapt. Tell us how you made 
these cloud-based solutions more relevant to your research or teaching 
duties.

Give feedback. If these cloud-based solutions have been useful to you, 
please let us know and we will allocate more resources to their 
continued improvement. Gitpod is now part of the ESPResSo code, but it 
is currently not tested in CI. The Binder solution relies on a feature 
that is still in Beta [12] and we are currently not storing it in the 
official ESPResSo organization.

Links:
[2] https://mybinder.org/v2/gh/jngrad/espresso-binder/HEAD
[3] https://gitpod.io/#https://github.com/espressomd/espresso
[4] https://www.gitpod.io
[5] https://github.com/jngrad/espresso-binder
[6] https://espressomd.github.io/doc/running.html#running-in-the-cloud
[7] https://www.gitpod.io/docs/configure/ssh
[8] https://jupyterlab.readthedocs.io/en/stable/user/rtc.html
[9] 
https://www.youtube.com/playlist?list=PLQ_NF7t8R523PB5YDpVOXDB8fBYQ9vBk7
[10] 
https://conference.scipy.org/proceedings/scipy2018/project_jupyter.html
[11] https://github.com/espressomd/espresso/blob/python/.gitpod.yml
[12] 
https://mybinder.readthedocs.io/en/latest/tutorials/dockerfile.html?highlight=beta