Skip to content

Commit ab4c52d

Browse files
IAlibayIAlibay
committed
Create copy of the remote MD course for future
1 parent b47523c commit ab4c52d

22 files changed

Lines changed: 2463 additions & 0 deletions

‎tutorials/MD/remote/00_Setup.ipynb‎

Lines changed: 361 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,361 @@
1+
{
2+
"cells": [
3+
{
4+
"cell_type": "markdown",
5+
"metadata": {},
6+
"source": [
7+
"# 0. Setup instructions for the MD course"
8+
]
9+
},
10+
{
11+
"cell_type": "markdown",
12+
"metadata": {},
13+
"source": [
14+
"This notebook contains the necessary instructions to make sure you have the correct software installed in order to complete the MD course.\n",
15+
"\n",
16+
"We assume here that you first looked at the `setup.md` prior to opening this notebook. If not, please do so now."
17+
]
18+
},
19+
{
20+
"cell_type": "markdown",
21+
"metadata": {},
22+
"source": [
23+
"## 0.1 Tutorial practicalities"
24+
]
25+
},
26+
{
27+
"cell_type": "markdown",
28+
"metadata": {},
29+
"source": [
30+
"## 0.1.1 Terminal (command line) instructions"
31+
]
32+
},
33+
{
34+
"cell_type": "markdown",
35+
"metadata": {},
36+
"source": [
37+
"Quite frequently in this tutorial you will be asked to run certain commands in your terminal, something which is also often known as \"command line instructions\".\n",
38+
"\n",
39+
"To make it clear as to what we expect you to type in your terminal, we add an \"%\" before the instruction. However this \"%\" should not be included.\n",
40+
"\n",
41+
"For example:\n",
42+
"\n",
43+
"```\n",
44+
"% echo \"test\"\n",
45+
"```\n",
46+
"\n",
47+
"Is asking you to type `echo \"test\"` + \"Enter\" in your terminal.\n",
48+
"\n",
49+
"Should these commands be confusing, please do not hesitate to ask one of the demonstrators at any point."
50+
]
51+
},
52+
{
53+
"cell_type": "markdown",
54+
"metadata": {},
55+
"source": [
56+
"## 0.2 Using ARCUS-HTC"
57+
]
58+
},
59+
{
60+
"cell_type": "markdown",
61+
"metadata": {},
62+
"source": [
63+
"In this course we will be using Oxford's Advanced Research Computing high performance cluster ARCUS-HTC in order to run GROMACS simulations.\n",
64+
"\n",
65+
"We suggest that you have a look at the ARC [Quick Start Guide](https://www.arc.ox.ac.uk/getting-started-guide) before continuing. The instructions provided here will repeat some of the basic details of the guide, but in much less detail."
66+
]
67+
},
68+
{
69+
"cell_type": "markdown",
70+
"metadata": {},
71+
"source": [
72+
"### 0.2.1 Getting an ARC account"
73+
]
74+
},
75+
{
76+
"cell_type": "markdown",
77+
"metadata": {},
78+
"source": [
79+
"We will be providing attendees of the Oxford Computational Biochemistry course with guest login accounts for ARCUS. Details, which include usernames and passwords, will be sent to you prior to the start of the course. We ask that you keep these details secure and that you do not share them.\n",
80+
"\n",
81+
"If you already have an ARCUS account, we still suggest that you use these guest accounts as we have obtained a specific reservation for the course which will allow you to run the simulations with minimal queuing time."
82+
]
83+
},
84+
{
85+
"cell_type": "markdown",
86+
"metadata": {},
87+
"source": [
88+
"### 0.2.2 Connecting to ARCUS-HTC"
89+
]
90+
},
91+
{
92+
"cell_type": "markdown",
93+
"metadata": {},
94+
"source": [
95+
"**Important Note - in all instances order to connect to the ARC computers you must be logged into the University VPN**\n",
96+
"\n",
97+
"As detailed in the [Quick Start Guide](https://www.arc.ox.ac.uk/getting-started-guide) access to ARCUS-HTC is achieved via the \"secure shell\" (SSH) protocol.\n",
98+
"\n",
99+
"SSH essentially allows you to securely access another computer via a network (i.e. the internet).\n",
100+
"\n",
101+
"Generally when using a machine like ARCUS-HTC, SSH access is achieved through the use of a terminal. The way in which this is done differs based on the type of computer you have. Here we will provide two separate set of instructions for setting up and testing connecting with ARCUS. Please follow the instructions which are appropriate to your computer."
102+
]
103+
},
104+
{
105+
"cell_type": "markdown",
106+
"metadata": {},
107+
"source": [
108+
"### 0.2.2.1 linux/macOS\n",
109+
"\n",
110+
"On linux/macOS connections to ARCUS can be done directly from the built-in terminal through the `ssh` command:\n",
111+
"\n",
112+
"```\n",
113+
"% ssh username@oscgate.arc.ox.ac.uk \n",
114+
"```\n",
115+
"\n",
116+
"Where `username` is your guest login account username. This will prompt you with a password (the one which was allocated to you alongside your guest account) which you will then enter:\n",
117+
"\n",
118+
"\n",
119+
"![oscgate-password.png](images/setup/ssh/oscgate-password-ssh.png)\n",
120+
"\n",
121+
"_note: as you can see my username here has been osbcured by a grey bar_\n",
122+
"\n",
123+
"On first login you may get a message with similar wording to:\n",
124+
"\n",
125+
"`The authenticity of host 'arcus-htc (10.137.128.21)' can't be established. RSA key fingerprint is d1:83:21:b1:f2:bd:???:cd:74:d1:73:???:?a., Are you sure you want to continue connecting (yes/no)?`\n",
126+
"\n",
127+
"In this case this is perfectly normal, please type `yes` and press \"Enter\". This may also happen when you log into `arcus-htc`.\n",
128+
"\n",
129+
"This connects you to `oscgate` the gateway computer for accessing ARC resources.\n",
130+
"In other words, it's the computer you log into in order to log into other computers owned by ARC.\n",
131+
"\n",
132+
"\n",
133+
"![oscgate-login.png](images/setup/ssh/oscgate-login-ssh.png)\n",
134+
"\n",
135+
"\n",
136+
"On login, you should then follow with:\n",
137+
"\n",
138+
"```\n",
139+
"% ssh arcus-htc\n",
140+
"```\n",
141+
"\n",
142+
"If successful you should find yourself in your home directory on the ARCUS-HTC computer where we will be running our jobs for the MD tutorial.\n",
143+
"\n",
144+
"\n",
145+
"![arcus-login.png](images/setup/ssh/arcus-htc-login-ssh.png)\n",
146+
"\n",
147+
"\n",
148+
"Typing:\n",
149+
"\n",
150+
"```\n",
151+
"% pwd\n",
152+
"```\n",
153+
"\n",
154+
"Should return: `/home/username` where `username` is your account username.\n",
155+
"\n",
156+
"This confirms that you are properly connected.\n",
157+
"\n",
158+
"Next we are going to create a file on ARCUS so that we can then test our ability to copy files back from ARCUS to our own computer.\n",
159+
"\n",
160+
"To do this we use the echo command:\n",
161+
"\n",
162+
"```\n",
163+
"% echo \"Hello World\" > file.txt\n",
164+
"```\n",
165+
"\n",
166+
"To make sure the file exists you can `more` the file to see its contents\n",
167+
"\n",
168+
"```\n",
169+
"% more file.txt\n",
170+
"```\n",
171+
"\n",
172+
"\n",
173+
"![ssh-helloworld.png](images/setup/ssh/ssh-helloworld.png)\n",
174+
"\n",
175+
"\n",
176+
"At this point, we are going to exit ARCUS. This is done by either completely closing the terminal or typing\n",
177+
"\n",
178+
"```\n",
179+
"% exit\n",
180+
"```\n",
181+
"\n",
182+
"twice\n",
183+
"\n",
184+
"\n",
185+
"![arcus-exist.png](images/setup/ssh/arcus-ssh-exit.png)\n",
186+
"\n",
187+
"\n",
188+
"Finally, we are going to test our ability to transfer files from ARCUS to our own computer. To do this we use the `scp` command which securely copies files from one computer to another:\n",
189+
"\n",
190+
"```\n",
191+
"% scp username@oscgate.arc.ox.ac.uk:/home/username/file.txt .\n",
192+
"```\n",
193+
"\n",
194+
"Where `username` is the guest account username that you were provided.\n",
195+
"\n",
196+
"If this works you should see that you now have a file named `file.txt` in the folder your terminal is currently in.\n",
197+
"\n",
198+
"\n",
199+
"![arcs-scp.png](images/setup/ssh/scp-arcus.png)\n",
200+
"\n"
201+
]
202+
},
203+
{
204+
"cell_type": "markdown",
205+
"metadata": {},
206+
"source": [
207+
"### 0.2.2.2 Windows\n",
208+
"\n",
209+
"Unlike linux/macOS, Windows does not natively support SSH connections from its terminal.\n",
210+
"\n",
211+
"Instead we have to install software to do this. Our (and ARC's) recommended solution here is [MobaXterm](https://mobaxterm.mobatek.net/).\n",
212+
"\n",
213+
"Upon installation and opening, MobaXterm will look something like this:\n",
214+
"\n",
215+
"\n",
216+
"![mobaxterm-main.png](images/setup/mobaxterm/mobaxterm-main.png)\n",
217+
"\n",
218+
"\n",
219+
"From there, we can start a new SSH session by clicking on `session`:\n",
220+
"\n",
221+
"\n",
222+
"![mobaxterm-session-ssh.png](images/setup/mobaxterm/mobaxterm-session-ssh.png)\n",
223+
"\n",
224+
"\n",
225+
"We then click on `SSH`:\n",
226+
"\n",
227+
"\n",
228+
"![mobaxterm-ssh-settings.png](images/setup/mobaxterm/mobaxterm-ssh-settings.png)\n",
229+
"\n",
230+
"\n",
231+
"We then find ourselves with a page with two fields to fill in, `Remote Host` and (once the tickbox is clicked) `Specify Username`.\n",
232+
"\n",
233+
"Here you would put `oscgate.arc.ox.ac.uk` as the entry for `Remote Host`, and your ARCUS guest account login name for `Specify Username`.\n",
234+
"\n",
235+
"Then press \"OK\" to start the ssh connection.\n",
236+
"\n",
237+
"Immediately you will be asked for a password, here put in the password you have been given.\n",
238+
"\n",
239+
"You should now be logged into `oscgate` the gateway computer for accessing ARC resources.\n",
240+
"In other words, it's the computer you log into in order to log into other computers owned by ARC.\n",
241+
"\n",
242+
"\n",
243+
"![oscgate-login.png](images/setup/ssh/oscgate-login-ssh.png)\n",
244+
"\n",
245+
"\n",
246+
"On first login you may get message with similar wording to:\n",
247+
"\n",
248+
"`The authenticity of host 'arcus-htc (10.137.128.21)' can't be established. RSA key fingerprint is d1:83:21:b1:f2:bd:???:cd:74:d1:73:???:?a., Are you sure you want to continue connecting (yes/no)?`\n",
249+
"\n",
250+
"In this case this is perfectly normal, please type `yes` and press \"Enter\". This may also happen when you log into `arcus-htc`.\n",
251+
"\n",
252+
"On login, you should then follow with:\n",
253+
"\n",
254+
"```\n",
255+
"% ssh arcus-htc\n",
256+
"```\n",
257+
"\n",
258+
"\n",
259+
"If successful you should find yourself in your home directory on the ARCUS-HTC computer where we will be running our jobs for the MD tutorial.\n",
260+
"\n",
261+
"\n",
262+
"![arcus-login.png](images/setup/ssh/arcus-htc-login-ssh.png)\n",
263+
"\n",
264+
"\n",
265+
"Typing:\n",
266+
"\n",
267+
"```\n",
268+
"% pwd\n",
269+
"```\n",
270+
"\n",
271+
"Should return: `/home/username` where `username` is your account username.\n",
272+
"\n",
273+
"This confirms that you are properly connected.\n",
274+
"\n",
275+
"Next we are going to create a file on ARCUS so that we can then test our ability to copy files back from ARCUS to our own computer.\n",
276+
"\n",
277+
"To do this we use the echo command:\n",
278+
"\n",
279+
"```\n",
280+
"% echo \"Hello World\" > file.txt\n",
281+
"```\n",
282+
"\n",
283+
"To make sure the file exists you can `more` the file to see its contents\n",
284+
"\n",
285+
"```\n",
286+
"% more file.txt\n",
287+
"```\n",
288+
"\n",
289+
"\n",
290+
"![ssh-helloworld.png](images/setup/ssh/ssh-helloworld.png)\n",
291+
"\n",
292+
"\n",
293+
"Copying a file is also different on Windows compared to linux/macOS. Instead of having to use `scp`, we can directly use the file browser within MobaXterm which should be present as a panel on the left side of the MobaXterm window.\n",
294+
"\n",
295+
"\n",
296+
"![mobaxterm-browser](images/setup/mobaxterm/mobaxterm-browser.png)\n",
297+
"\n",
298+
"\n",
299+
"You can directly drag a file/folder from this file browser into a folder in your computer to download it.\n",
300+
"\n",
301+
"Finally just open the file to check that you have downloaded it properly.\n",
302+
"\n",
303+
"\n",
304+
"![mobaxterm-ftp](images/setup/mobaxterm/mobaxterm-ftp.png)\n",
305+
"\n",
306+
"\n",
307+
"Now we need to exit, to do so on MobaXterm all you need to do is press the red `Exit` button on the top right hand side of the terminal.\n",
308+
"\n",
309+
"\n",
310+
"![mobaxterm-exit](images/setup/mobaxterm/mobaxterm-exit.png)\n",
311+
"\n"
312+
]
313+
},
314+
{
315+
"cell_type": "markdown",
316+
"metadata": {},
317+
"source": [
318+
"## 0.3 VMD (optional)"
319+
]
320+
},
321+
{
322+
"cell_type": "markdown",
323+
"metadata": {},
324+
"source": [
325+
"\n",
326+
"\n",
327+
"![VMD main](images/setup/vmd.png)\n",
328+
"\n",
329+
"\n",
330+
"[VMD](https://www.ks.uiuc.edu/Research/vmd/) is a powerful tool for the visualisation of molecular systems. It can be obtained from the [VMD download page](https://www.ks.uiuc.edu/Development/Download/download.cgi?PackageName=VMD).\n",
331+
"\n",
332+
"Unfortunately due to issues with various operating systems, VMD is often difficult to install (for example, it is not currently officially supported on macOS Catalina or Big Sur). The exercises which use VMD will therefore be optional. As an alternative molecular viewer, we will be using [NGLView](http://nglviewer.org/nglview/latest/api.html).\n",
333+
"\n",
334+
"Nevertheless, we encourage you to try to install it if possible. VMD is one of the most widely used tools for biomolecular simulation visualisation and analysis. Being able to use it here would provide you with a good opportunity to familiarise yourself with some of its many features within the context of this tutorial.\n",
335+
"\n",
336+
"Due to the complexities of installing VMD, we leave it up to you to decide if you wish to do so and also to work out how to install it for your own computer. Unfortunately due to the large variations in the installation process between computers, it is possible that we will be unable to offer advice for your own computer setup."
337+
]
338+
}
339+
],
340+
"metadata": {
341+
"kernelspec": {
342+
"display_name": "Python 3",
343+
"language": "python",
344+
"name": "python3"
345+
},
346+
"language_info": {
347+
"codemirror_mode": {
348+
"name": "ipython",
349+
"version": 3
350+
},
351+
"file_extension": ".py",
352+
"mimetype": "text/x-python",
353+
"name": "python",
354+
"nbconvert_exporter": "python",
355+
"pygments_lexer": "ipython3",
356+
"version": "3.7.7"
357+
}
358+
},
359+
"nbformat": 4,
360+
"nbformat_minor": 4
361+
}

0 commit comments

Comments
 (0)