HOW-TO Get started¶

To start, a few initial steps need to be taken. Access is required to the AWE database, software and dataservers.

Access to the AWE database¶

A database account is needed in order to use the AWE system. To get a database account, ask your local AWE representative [1] to create one for you. Your database username will consist of AW, followed by your first initial, followed by your surname.

Preparing the Astro-WISE Environment¶

In order to automatically log in to the database when you start up AWE you need to create a directory .awe in your home directory:

cd
mkdir .awe
cd .awe

Now create a file here called Environment.cfg with the following content:

[global]
database_user     : <your database username>
database_password : <your database password>

Make sure only you can read the contents of the file:

chmod a-rwx,u+rw Environment.cfg

At OmegaCEN/Kapteyn Astronomical Institute, the AWE software is set up using Modules:

module add awe

Starting the Astro-WISE Environment¶

To start AWE type:

awe

and you will be welcomed by an prompt similar to this:

Python 3.5.1 (default, Nov  1 2016, 21:12:07)
[GCC 4.8.5 20150623 (Red Hat 4.8.5-4)] on linux
Type "help", "copyright", "credits" or "license" for more information.


               Welcome to the Astro-WISE Environment


Importing Astro-WISE packages. Please wait...


Distributed Processing Unit: dpu.hpc.rug.astro-wise.org
Dataserver: ds.astro.rug.astro-wise.org

Current profile:
- username : <your database username>
- database : db.astro.rug.astro-wise.org
- project  : <your active project>
- current privileges : 1 (MyDB)
awe>

From this moment on the Astro-WISE Environment is at your disposal. Use Ctrl-d to exit.

Jupyter notebook setup¶

You can also use Astro-WISE in an IPython notebook environment. The executable jawe can be used to start a jupyter notebook server. First create the configuration file:

jawe notebook --generate-config

This should create the jupyter configuration file in your home directory:

~/.jupyter/jupyter_notebook_config.py

By default the Jupyter webserver is not password protected and anyone connecting to it can execute commands as yourself. Let’s create a password hash in the awe-prompt. Start awe:

awe

Then create a sha1 password hash:

awe> from notebook.auth import passwd
awe> passwd()
Enter password:
Verify password:
'sha1:<some hash>'

Copy this hash to your Jupyter configuration file:

c.NotebookApp.password = ''

You can now start the notebook server:

jawe notebook

Access to the AWE software¶

After gaining experience with AWE you have the option to change the source code and make the changes available to AWE, so they are shared with other users. This is done via Git, and the following sections explain how to get read access and write access to the AWE software.

Master and develop version¶

It is important to note at this point that we maintain two branches in Git: master and develop. We recommend that you use the master version.

Read-only access to the AWE software¶

If you’d like to change the AWE software, you first need to get it via Git.

Usage of Git is explained in HOW-TO Use Git.

Note that in order to use your checkout of awe instead of the central checkout, you have to set an environment variable AWEPIPE to point to the awe directory. C-shell example:

setenv AWEPIPE /path/to/your/awe

It may be convenient to add this line to your ~/.cshrc configuration file.

Write access to the AWE software¶

If you are granted write access, you can share your improvements of and additions to the source code with the Astro-WISE community.

Setting up write access to the Git repository is further explained in HOW-TO Use Git.

Access to the AWE dataservers¶

Access to the dataservers is automatically taken care of and does not require any action on the part of the user.

[1]	At OmegaCEN/Kapteyn Astronomical Institute, contact danny@astro.rug.nl or kgb@astro.rug.nl