Visions:NoobiesTutorial

Abbreviated Names

 ASA: Aamir, Syed Ahmed
 AG:  Andreas Grübl
 AH:  Andreas Hartel
 BK:  Björn Kindler
 BV:  Bernhard Vogginger
 CK:  Christoph Koke
 CM:  Christian Mauch
 CP:  Christian Pehle
 DH:  Dan Husmann
 ECM: Eric Müller
 FK:  Felicitas Kleveta
 IB:  Ilja Bytschok
 JB:  Johannes Bill
 JK:  Johann Klähn
 JS:  Johannes Schemmel
 KHS: Kai Husmann
 KM:  Karlheinz Meier
 LL:  Luziwei Leng
 MAP: Mihai Petrovici
 MD:  Markus Dorn
 MG:  Maurice Güttler
 MK:  Mitja Kleider
 OA:  Oscar Martín-Almendral
 OB:  Oliver Breitwieser
 PM:  Paul Müller
 SS:  Sebastian Schmitt
 TP:  Tom Pfeil
 VK:  Vitali Karasenko

KIP Institute Login

The KIP login process is used for both, physical (i.e. keys) and virtual (i.e. user login stuff) access to KIP facilities. All F9 group services use some kind of KIP account/authentication. The login form can be found here: https://www.kip.uni-heidelberg.de/service/verwaltung/form_forms (needs KIP login).

Rules (as a hint for your supervisor) regarding the "LOGIN Computing" part:

• state that the student should be added to kip_vision mailing list (IT)
• same for kip visions wiki (IT)
• chip design permission if needed
• internshippers and bachelor students should be assigned to primary group F9_guests (field "3")
• master students and beyond should be assigned to primary group F9 (field "3")

Meetings, sorted by time

Meeting Title	Description	Location	Datetime	Manager
Hardware Users Meeting	Users and hardware guys discussing about current topics related to hardware usage.	ENI	Weekly, Monday at 10:30	SS (backup: PM or ECM)
HICANN DLS Meeting	Chip design meeting	ENI	Weekly, Tuesday at 10:00	JS
DLS Users Meeting	HICANN DLS users meeting (DLSHWFUM)	ENI	Weekly, Wednesday at 10:00	CM
Softies' Meeting	Mandatory Softies meeting ;). Logs and agenda can be found here.	ENI	Weekly, Tuesday at 14:00	ECM
FPGA Development	Logs and agenda can be found here.	ENI	Weekly, Tuesday at 15:30	AG (backup: ECM).
Journal Club	Stay up-to-date with scientific literature (one featured publication + spot lights)	ENI	Weekly, Wednesday at 11:00	JB, AH
TMA Meeting	Logs and agenda can be found here.	ENI	Weekly, Wednesday at 14:00	MAP
ASIC Meeting		Seminarbox 1.Stock KIP, SB1	Weekly, Wednesday at 16:00, alternating between ASIC classic and ASIC DLS	JS
F9/Electronic Vision(s)' Group Meeting	Mandatory group meeting. Logs and agenda can be found here (login using BrainScaleS account).	ENI	Weekly, Thursday at 9:00	JS
PCB Meeting	PCB and System-Design related discussions. Platform setup and installation also covered.	ENI	Weekly, Thursday at 15:00	AG

Workplace

Computers

We use a Debian Jessie-based default installation. The configuration is automatically managed. In case of package requests, please ask KHS. Bugs and requests should be posted here.

The spack package manager is used to provide modules, if you run into issues try to find your question here.

Space

There are some places in the "Werkstatt" building (room 501) and in the container building. In case of a transient shortage of spaces, internshippers and bachelors are expected to "fill up" (i.e. they do not have a static assignment to a specific place) all available places.

Network

If you want to use your own laptop inside the KIP network, you first need to register your laptop's MAC address. AG, JS are allowed to edit the list.

From inside the KIP network, outgoing traffic has to go through the EDV:KIPProxy. You can create a proxy auto-config file, e.g. /etc/proxy.pac and configure your browser and system to use it. This way you do not need to manually switch proxy settings when switching between KIP and other networks.

function FindProxyForURL(url, host)
{
  if (isInNet(myIpAddress(), "129.206.180.0", "255.255.255.0")) {
    if (isInNet(host, "129.206.0.0", "255.255.0.0")) {
      return "DIRECT";
    }
    return "PROXY proxy.kip.uni-heidelberg.de:8080" ;
  } else {
    return "DIRECT";
  }
}

Communication

To stay informed (and to provide information to others) you should join F9's own slack-like chat server on chatviz. The main channels are:

Channel	Topic
#softies	Software and stuff
#hardies	Hardware
#tma	Modeling
#clusteraner	Cluster usage and announcements

You should create an account on https://brainscales-r.kip.uni-heidelberg.de:6443/visions (externally reachable).

The software also supports IRC access via port 6667 (KIP-internally).

Examples for IRC Clients:

• hexchat (GUI)
• weechat-curses (CLI)
• Pidgin (GUI) / finch (CLI)

You can access the channels in Pidgin by creating a new account (Accounts -> Manage Accounts) using the Protocol IRC on server "chatviz" port 6667. To authenticate yourself, add a "buddy pounce" on pseudo user "mattermost" and send "LOGIN yourMailaddress yourPassword" (recurring).

Accounts

Typically, you will need the following accounts:

• KIP-Account (see KIP Institute Login)
• Flagship/ex-BrainScaleS-Account (which provides Access to the gitviz-Repository)

If you work on the waferscale hardware or need access to the computer cluster ask your supervisor to write an email to ECM (+ get an introduction by your supervisor). If you do chip or FPGA development, you need ASIC permissions. Ask your supervisor to write an email to MD (+ get an introduction by your supervisor).

Flagship/ex-BrainScaleS

Flagship/ex-BrainScaleS accounts are managed by BK. You can contact him directly. This account is also needed for Redmine/GitViz access.

Redmine/GitViz Permissions

When your login works, please create ssh keys (as indicated in [1]) and upload the key to gitviz. Afterwards you should ask the project managers to add you to the needed repositories (your supervisor can help you). In case of ssh-key fails, please stick to the description in the symap2ic wiki (it's always the user's fault ;p). If you need further help, you may ask ECM/KHS/JS, the gitviz/redmine administrators.

Cluster Access

The F9 cluster is part of the BrainScaleS and HBP hardware systems. In times of idle nodes (i.e. the associated neuromorphic hardware parts are idle too), conventional software simulations can be run on the system. Please note, the cluster's main objective is controlling neuromorphic hardware and not number crunching. Having a KIP-Account gives you a home folder (distributed filesystem, AFS) on all machines running the default installation. However, this is not sufficient for cluster usage. You need a "wang" home and cluster access permissions. Both is managed by ECM and KHS. In case of a missing cluster_home you will see an error message when you lock into a compute server.

The frontend/login nodes are named:

• ice
• ignatz

and you can access them via (example for ice, but works with any other name too) ssh -X ice

If you are working from outside the institute, you can access the frontend via ssh -p <port> <kipuser>@brainscales-r.kip.uni-heidelberg.de The following ports give access to:

• 7022: ice
• 11022: hel
• 12022: beli

Server Usage

The machines mentioned above are not the compute nodes themselves, but are only the frontend to access the compute cluster. Large jobs (i.e. CPU/IO hogs or long-running things) on the frontend node will be killed by the administrators. So for heavy work (read everything after the bug/syntax fixing) please dispatch execution to the cluster:

 srun -p [partitionname] [your command]

The default job gets 1 CPU and 2GB of RAM. If your code runs in parallel or needs more memory, please specify this (e.g. 4 CPUs, 8GB RAM):

 srun -p compile -c 4 --mem 8G [your command]

To run the job in background, please use:

 sbatch  -p simulation --wrap [your command]

This creates a slurm-[jobid].out log file containing all the console output.

In order to check the status of your jobs the command squeue can be used. For detailed information do:

 scontrol show jobid -dd <jobid>

Jobs can be aborted (cancelled) by using:

 scancel [jobid]

Accessing the BrainScaleS hardware is only possible via the experiment queue. Spikey is accessible via spikey queue. To select a specific spikey, the --gres=SpikeyXYZ option is used. DLS is accessible via dls queue. To select a specific dls board, the --gres=[board id] option is used.

More details can be found here [2].

As a side note the compute nodes have localtime set to UTC, so all logging times will be offset to local time. However, this should never be a problem as you should always work with non-local date/time (e.g. UNIX epoch, UTC or something similar).

X on cluster nodes

Although not recommended, some old tools require X support. Follow the instructions at [3] if you encounter such an old tool.

FPGA & ASIC

Servers, software and libraries are managed by MD.

Servers

There are several login nodes for ASIC work, e.g., vmimas, vtitan, vrhea.

B.Sc.

Thesis

• When thinking about how to structure your thesis, consider these internal recommendations.

B.Sc. colloquium / Theses hand-in dates

• Find a suitable date for your colloquium and other things (KM & JS & you). A lot of people have full schedules, so do it well in advance!
• Set all the dates, inform the examination office (Prüfungssek.) and make sure that Felicitas Kleveta is up2date, too.

Administrative Stuff

Travel

• before travel: fill out travel request form (Dienstreiseantrag) and hand over to FK
• after travel: fill out reimbursement form (Dienstreiseabrechnungsformular) (provide invoices etc.) and hand over to FK
• when getting back the result: check if everything is correct, hand over to OA

The forms can be found here: https://www.kip.uni-heidelberg.de/service/verwaltung/form_forms (needs KIP login).

Internships

Schein

Windows Software

If you need Windows software, e.g. to fill out forms (Word, Excel), you can log in remotely to a Windows machine:

rdesktop kipwin

Using The Hardware

The HBP SP9 Guidebook provides introductions to both, the Spikey system and the BrainScaleS system.

Core Hardware Components

For the BrainScaleS system, the NMPM hardware specification provides detailed information; see Jenkins doc job "HBP Spec". TODO: Write something about hardware stuff.

Data Management

The policy on F9-specific data storage is:

KIP/F9 Data Storage

Mount Point	Storage Backend	Redundancy	Backup Strategy	Usable Size	User Quota	Typical Application
/afs/kip/user/USERNAME	HDD	RAID	yes (1 version)		10G	Distributed home directory
/scratch			no			Scratch/temp data; might be deleted at any time
/wang	HDD	RAID6 (2R)	no	13T	0.3T	General purpose
/ley	HDD	RAID6 (2R)	yes (ADSM; 1 version)	7T	0.1T	Important stuff (not too large!)
/loh	4x Archive HDD	RAID5 (1R)	no	16T	1T	Archives of machines, homes, etc.
???	SSD		no

Software Development

Most (all?) software developers work remotely on server machines. Tools like screen or tmux can keep your session open between reconnects.

Git

As a general rule, everything should be tracked in a version control system, in our case, that is git. Period. If you hear git for the first time I highly recommend spending an hour going through a git tutorial of your choice. Here are some examples:

• The Simple Guide
• TODO add one or two more?

Whether your own work should be tracked in the group gitviz or not, should be decided together with your supervisor. But mostly, you will need to checkout some repo for read access. If your own/private work is not for the trash, you should request a repository (or contribute to an existing one) on gitviz. Have your supervisor ask KHS for a repository.

Accessing external repositories using the git or ssh protocol requires the user to call socksify or tsocks:

 socksify git clone git://external.server/repo.git # on wheezy default installation
 tsocks git clone git://external.server/repo.git # on 'new' jessie default installation

License

Keep your code contributions (L)GPL-clean because we might want to publish it on a public web site. If you copy code from somewhere, verify license compatibility and mention the source as a code comment!

Code Review

For core software components (and other repositories involving multiple developers), we use gerrit as a code review tool. The server F9's Gerrit Server and a small tutorial can be found here [4].

Continuous Integration

We encourage continuous and automatic testing, see F9's Jenkins Server. Contact KHS for details.

Bug reports and redmine project management

Bugs should be posted immediately in the redmine project associated with the module that produced the error. The title should be descriptive (it may only be changed by 'project managers' after creating the ticket). As a general rule, the traceback is necessary for the developer to find the actual bug, but the more relevant information are given the easier the fix. Ideally, you create a minimal example that reproduces the problem and upload the script, including the module's loaded. F9's Redmine Server

How to: Building Software

• log onto frontend (exp: hel)

  > ssh hel

• Create and switch to project directory (choose path according to personal preference):

  > mkdir -p code/project_name
  > cd code/project_name

• Load the waf build tool module. More information on waf

  > module load waf

• Normally ssh will ask for the password of your private key every time you connect to another machine (e.g. during git pull). If you want to avoid this you can start ssh-agent, which will load/unlock your private key by asking you once and keep running in the background.

  > eval $(ssh-agent)

• Add your personal ssh key agent to the agent (link -> create key?)

  > ssh-add

• Choose the wanted project (exp: sthal)

  > waf setup --project sthal
  # ——— or specify multiple projects: ———
  > waf setup --project sthal --project cake

• Load project dependencies via the current spack module which you can find in the MOTD for hel. A small introduction to spack you can find here.

  > module load spack_visionary-defaults/2017-01-26_0.2.3

• Configure and compile on the cluster. The default job gets 2 CPUs and 2GB of RAM. If your code runs in parallel or needs more memory, please specify this (e.g. 8 CPUs, 20GB RAM):

  > srun -p compile -c8 --mem 20g --pty waf configure install

Core Software Components

This section gives a very brief description of the main software packages developed for the NMPM-1 and Spikey systems. Short introduction on how to get and build repos https://brainscales-r.kip.uni-heidelberg.de/projects/waf/wiki/Wiki

PyNN

A python API to specify neural networks, independent of the actual simulator used. Typical use case is to use it as frontend for simulations in nest or neuron. Documentation is available on its webpage (sort of at least) [5], in order to get started it is best to ask someone for a simple working script and trying to reproduce it with minor changes (ideally your supervisor has some propositions for you)

PyHMF

The BrainScaleS-hardware-specific PyNN implementation/backend. Maintainers: ECM, CK

PyNN.hardware/PyHAL

The Spikey-hardware-specific PyNN implementation/backend. Maintainers: TP (backup: ECM)

Cake

Calibration framework for the BrainScaleS hardware. Maintainers: SS and MK

Euter/Ester

The C++-layer providing a representation of neuronal network descriptions (generated by PyHMF) -- used for BrainScaleS hardware. Maintainers: ECM, CK

Marocco

The translation layer which converts abstract neuronal networks into a hardware bit stream (i.e. a valid hardware configuration) -- used for BrainScaleS hardware. Maintainers: ECM, SS

StHALbe, hicann-system

StHAL, HALbe and hicann-system are the hardware access layers -- used for BrainScaleS hardware. Maintainers: ECM, CK

SpikeyHAL

Spikey hardware access layer. Maintainers: TP (backup: AG or ECM)

HostARQ

The communication protocol stack for communication between the BrainScaleS hardware (FCP FPGAs) and host computers. Maintainers: ECM, CM

ESS

The Executable System Specification is a BrainScaleS hardware simulator. Originally developed as a chip verification software by AG, it evolved into a neuronal network simulator (by BV). Maintainer: BV, OB

Modeling Software Packages

SBS

Allows for simple creation and sampling of and with Boltzmann machines of PyNN neurons. See Tutorial Maintainer: OB

TODO: Tutorial link is dead!