Remeis-Wiki - User contributions [en]

Travel

2025-05-23T10:26:43Z

Wilms: /* List of project funds */

[[Category:Internal]]

This page documents how to apply for business travel and hand in the reimbursement with the online tool accessible through [https://www.mitarbeiterservice.bayern.de/ authega]. This requires you to have an account set up. If you sign up for the first time you will be send a letter (! yes, physical letter, this can take some days) with information for the login. For further logins it is best to use a certificate file with a password.

Once logged in you can access the travel management (Reisekostenmanagement, RMS) and enter the necessary information there. Certain numbers are tied to the observatory and will always be the same, they are documented below. '''Note:''' When selecting the institution (Beschäftigungsbehöde) do '''not''' use the Remeis-Observatory or any other smaller body. Instead use the general FAU entry with the number '''1519016'''!

More information for the general setup are in the [[:Media:introduction_bayrms.pdf|introductory slides]] (this is the German version, see below for additional guidance in English).

In order to receive documents per email you need to sign the [[:Media:Bayrms_data_protection.pdf|data protection waiver]] (in German!) and hand it in (in paper form!).

== Application for business travel ==

Some notes on filling in these forms:

=== Travel days (Reisetage) ===
On each day, you need to input the start and end of your "business".
If you are, say attending a conference starting Monday at 2 PM and ending on a Friday at noon, your times should look like this:
* Monday: Start at 14:00, end at '''23:59'''
* Tue-Thur: Start at '''0:00''', end at '''23:59'''
* Fri: Start at '''0:00''', end at 12:00

The point here being that you are still there "on business" even outside the main conference hours. Weekends are also part of the trip, if the conference is more than one week long, so this is not "private time" in this form ((c) - Joern)

(NB: There are still discussions between the administration and Joern about this)

=== Meals ===
If food is provided by hotel/conference and you do not pay for it extra - make the corresponding mark in the day

=== Mitzeichner (Signatory, in the very end of the form) ===
This needs to be your boss, who will then forward it to P6.

=== Mitreisende ===
Only employees of Bavaria (e.g., if you drive from work with someone)

=== Hotel costs ===
It is good if you have some proof why you have taken this particular option. Get some documentation (e.g., print web-page with costs) at the moment of booking, which would display other possible options in this hotel or in other hotels around.

If you travel with family, you will not be reimbursed for the difference between the single room and the room you've taken (e.g., double), so you need to document the difference of the room cost AT THE TIME OF BOOKING.

If you are staying somewhere without having to pay, choose "unentgeltliche Uebernachtung".

=== Reimbursement in advance ===
According to Edith, reimbursement in advance requires entering a remark at the end of the form, i.e., state how much you would like to get reimbursed and put this in
the remarks field. As a rule of thumb, this should not include per diems and the like, but can include travel and accommodation costs.

After approval, print the summary and give it to Edith.

== Handing in reimbursement ==

== List of project funds ==

Below is a list of project funds that you travel might be paid from. '''Before submitting your reimbursement form ask your supervisor what project to use! Every time!'''

{| class="wikitable" style="margin:auto"
|+ Project numbers
|-
! Name !! Erweiterung !! Kapitel !! Titel !! Info 1 (AWK) !! Kostenstelle
|-
| DLR 50 OR 2309 (VF-ULX) || 7401171 || 1519 || 54741 || || 1415151100
|-
| DLR 50 OO 2417 (THESEUS) || 7401182 || 1519 || 54741 || || 1415151100
|-
| DLR 50 OR 2410 (VF-XMM Aafia) || 7401186 || 1519 || 54741 || || 1415151100
|-
| DLR 50 QR 2503 (eROSITA) || 7401188 || 1519 || 54741 || || 1415151100
|-
| DLR 50 QR 2508 (ATHENA) || 7401191 || 1519 || 54741 || || 1415151100
|-
| DLR 50 OO 2507 (AXIS) || 7401196 || 1519 || 54741 || || 1415151100
|-
| || || || || ||
|-
| DFG WI 1860/19-1 (eRO STEP 1, P6) || 7458046 || 1519 || 54741 || || 1415151100
|-
| DFG WI 1860/20-1 (FOR 5195, P2) || 7458065 || 1519 || 54741 || || 1415151100
|-
| DFG WI 1860/17-2 (eRO STEP 2, P5) || 7458208 || 1519 || 54741 || || 1415151100
|-
| DFG WI 1860/21-1 (eRO STEP 2, P7) || 7458209 || 1518 || 54741 || || 1415151100
|-
| || || || || ||
|-
| DFG overhead WI until 2022 || 5002344 || 1519 || 54740 || PPS || 1415151100
|-
| DFG overhead WI from 2023 || 0150234 || 1519 || 54740 || PPS || 1415151100
|-
| || || || || ||
|-
| ESA (DALI) || 7402745 || 1519 || 54741 || || 1415151100
|-
| Wlms Altprojekte || 7402304 || 1519 || 54741 || || 1415151100
|-
| ETI Förderung || 5500245 || 1519 || 54741 || || 1415151100
|-
| || || || || ||
|-
| DFG SA 2131/13-2 (eRO STEP 2, P1) || 7458204 || 1519 || 54741 || || 1415150013
|-
| DFG SA 2131/14-2 (eRO STEP 2, P2) || 7458205 || 1519 || 54741 || || 1415150013
|-
| DFG SA 2131/15-2 (eRO STEP 2, TP Z) || 7458206 || 1519 || 54741 || || 1415150013
|-
| DFG SA 2131/18-1 (eROSITA Galaxien) || 7458168 || 1519 || 54741 || || 1415150013
|-
| || || || || ||
|-
| DFG overhead SA (Altprojekte) || 7459704 || 1519 || 54741 || || 1415150013
|-
| DFG overhead SA bis 2022 || 5002391 || 1519 || 54740 || PPS || 1415150013
|-
| DFG overhead SA ab 2023 || 0150178 || 1519 || 54740 || PPS || 1415150013
|-
| || || || || ||
|-
| DFG SA 4388/2-1 (Saeedi) || 7458207 || 1519 || 54741 || || 1415150013
|-
| DFG MA 11073/1-1 (Mayer) || 7458221 || 1519 || 54741 || || 1415150013
|-
| DFG HE 1356/70-2 (Heber) || 7458225 || 1519 || 54741 || || 1415150000
|-
| || || || || ||
|-
| 73er Titel || 0610006 || 1519 || 54740 || FuL || 1415150000
|-
| 72er Titel || 8063141 || 1519 || 54741 || || 1415150000
|}

Additionally, on the form containing the KLR data you need to specify the following:

* KLR-Verfahren: FAUKLR
* Buchungskreis: 0001
* Kostenart: 685000
* Kostenstelle: see above
* KLR Info 1: see above, leave empty if no info is given above
* KLR Info 2: your Zahlungspartner Nummer, as obtained from the idm

All other fields should be left empty.

== English information ==

Here are some PDFs you might find helpful to navigate through the German landscape of bureaucracy.

Some [[:Media:Additional_information_BayRMS.pdf|additional information]] in Englisch

The [[:Media:Bayrms_eng_data_protection.pdf|data protection waiver]] (you still have to sign the German one!)

The [[:Media:Bayrms_eng_introduction_slides.pdf|introduction slides]]

A [[:Media:Bayrms_glossary.pdf|glossary]] to match English and German terms. (REALLY HELPFUL, CONTAINS INFORMATION TO INSERT)

== ''OUTDATED!'' Business and private travels ==

If you intend to combine a business trip with a vacation to save money or just because of the occasion, you need to observe a couple of issues:

* first of all, combining business and private travel is in principle nothing that the university likes
* you *need* to get the private travel authorized on the travel request form, i.e. you need to state *both* on travel request form
* obviously you will not get any reimbursement for the private part of your trip, or any extra expenses arising from your vacation
* to get reimbursement for your business part of the trip, you need to document what the business part alone would have cost. In detail this means that you need to document:
* fictitious cost of flights/train tickets/rental car/etc for the business part of the trip
* fictitious cost of flights/train tickets/etc to and from the business destination of the trip
* nevertheless you also obviously need to state your actual cost (flight tickets etc).
* the university will reimburse you only the *lesser* of your actual cost and the fictitious cost!\\ This means that if your flight would have cost 1000 Eur, but because you stayed longer for private reasons (i.e. over the weekend) and the actual flight is cheaper like 700 Eur, the university will only reimburse you 700 Eur.

Furthermore apart from the reimbursement by the university, you have also to consider the taxes: the fiscal authorities might consider such a combination of business and private trip entirely private and therefore the reimbursement as additional income. So far,
this has never happened in Bamberg to Jörns knowledge, but in principle tax
regulations state that for a trip to count as a business trip, the
business portion must outbalance the private portion. To give an
example: a 3d observing run in Australia followed by a 2 week vacation
there would probably not be seen as a business related trip (even if it
was!), even though the university would reimburse you for your flights
and the 3d per diem.
((Based on a FAQ Email sent by Jörn to allusers on April 4, 2011))

Travel

2025-05-23T10:25:26Z

Wilms: /* List of project funds */

[[Category:Internal]]

This page documents how to apply for business travel and hand in the reimbursement with the online tool accessible through [https://www.mitarbeiterservice.bayern.de/ authega]. This requires you to have an account set up. If you sign up for the first time you will be send a letter (! yes, physical letter, this can take some days) with information for the login. For further logins it is best to use a certificate file with a password.

Once logged in you can access the travel management (Reisekostenmanagement, RMS) and enter the necessary information there. Certain numbers are tied to the observatory and will always be the same, they are documented below. '''Note:''' When selecting the institution (Beschäftigungsbehöde) do '''not''' use the Remeis-Observatory or any other smaller body. Instead use the general FAU entry with the number '''1519016'''!

More information for the general setup are in the [[:Media:introduction_bayrms.pdf|introductory slides]] (this is the German version, see below for additional guidance in English).

In order to receive documents per email you need to sign the [[:Media:Bayrms_data_protection.pdf|data protection waiver]] (in German!) and hand it in (in paper form!).

== Application for business travel ==

Some notes on filling in these forms:

=== Travel days (Reisetage) ===
On each day, you need to input the start and end of your "business".
If you are, say attending a conference starting Monday at 2 PM and ending on a Friday at noon, your times should look like this:
* Monday: Start at 14:00, end at '''23:59'''
* Tue-Thur: Start at '''0:00''', end at '''23:59'''
* Fri: Start at '''0:00''', end at 12:00

The point here being that you are still there "on business" even outside the main conference hours. Weekends are also part of the trip, if the conference is more than one week long, so this is not "private time" in this form ((c) - Joern)

(NB: There are still discussions between the administration and Joern about this)

=== Meals ===
If food is provided by hotel/conference and you do not pay for it extra - make the corresponding mark in the day

=== Mitzeichner (Signatory, in the very end of the form) ===
This needs to be your boss, who will then forward it to P6.

=== Mitreisende ===
Only employees of Bavaria (e.g., if you drive from work with someone)

=== Hotel costs ===
It is good if you have some proof why you have taken this particular option. Get some documentation (e.g., print web-page with costs) at the moment of booking, which would display other possible options in this hotel or in other hotels around.

If you travel with family, you will not be reimbursed for the difference between the single room and the room you've taken (e.g., double), so you need to document the difference of the room cost AT THE TIME OF BOOKING.

If you are staying somewhere without having to pay, choose "unentgeltliche Uebernachtung".

=== Reimbursement in advance ===
According to Edith, reimbursement in advance requires entering a remark at the end of the form, i.e., state how much you would like to get reimbursed and put this in
the remarks field. As a rule of thumb, this should not include per diems and the like, but can include travel and accommodation costs.

After approval, print the summary and give it to Edith.

== Handing in reimbursement ==

== List of project funds ==

Below is a list of project funds that you travel might be paid from. '''Before submitting your reimbursement form ask your supervisor what project to use! Every time!'''

{| class="wikitable" style="margin:auto"
|+ Project numbers
|-
! Name !! Erweiterung !! Kapitel !! Titel !! Info 1 (AWK) !! Kostenstelle
|-
| DLR 50 OR 2309 (VF-ULX) || 7401171 || 1519 || 54741 || || 1415151100
|-
| DLR 50 OO 2417 (THESEUS) || 7401182 || 1519 || 54741 || || 1415151100
|-
| DLR 50 OR 2410 (VF-XMM Aafia) || 7401186 || 1519 || 54741 || || 1415151100
|-
| DLR 50 QR 2503 (eROSITA) || 7401188 || 1519 || 54741 || || 1415151100
|-
| DLR 50 QR 2508 (ATHENA) || 7401191 || 1519 || 54741 || || 1415151100
|-
| DLR 50 OO 2507 (AXIS) || 7401196 || 1519 || 54741 || || 1415151100
|-
| || || || || ||
|-
| DFG WI 1860/19-1 (eRO STEP 1, P6) || 7458046 || 1519 || 54741 || || 1415151100
|-
| DFG WI 1860/20-1 (FOR 5195, P2) || 7458065 || 1519 || 54741 || || 1415151100
|-
| DFG WI 1860/17-2 (eRO STEP 2, P5) || 7458208 || 1519 || 54741 || || 1415151100
|-
| DFG WI 1860/21-1 (eRO STEP 2, P7) || 7458209 || 1518 || 54741 || || 1415151100
|-
| || || || || ||
|-
| DFG overhead WI until 2022 || 5002344 || 1519 || 54740 || PPS || 1415151100
|-
| DFG overhead WI from 2023 || 0150234 || 1519 || 54740 || PPS || 1415151100
|-
| || || || || ||
|-
| ESA (DALI) || 7402745 || 1519 || 54741 || || 1415151100
|-
| Wlms Altprojekte || 7402304 || 1519 || 54741 || || 1415151100
|-
| ETI Förderung || 5500245 || 1519 || 54741 || || 1415151100
|-
| || || || || ||
|-
| DFG SA 2131/13-2 (eRO STEP 2, P1) || 7458204 || 1519 || 54741 || || 1415150013
|-
| DFG SA 2131/14-2 (eRO STEP 2, P2) || 7458205 || 1519 || 54741 || || 1415150013
|-
| DFG SA 2131/15-2 (eRO STEP 2, TP Z) || 7458206 || 1519 || 54741 || || 1415150013
|-
| DFG SA 2131/18-1 (eROSITA Galaxien) || 7458168 || 1519 || 54741 || || 1415150013
|-
| || || || || ||
|-
| DFG overhead SA (Altprojekte) || 7459704 || 1519 || 54741 || || 1415150013
|-
| DFG overhead SA bis 2022 || 5002391 || 1519 || 54740 || PPS || 1415150013
|-
| DFG overhead SA ab 2023 || 0150178 || 1519 || 54740 || PPS || 1415150013
|-
| || || || || ||
|-
| DFG SA 4388/2-1 (Saeedi) || 7458207 || 1519 || 54741 || || 1415150013
|-
| DFG MA 11073/1-1 (Mayer) || 7458221 || 1519 || 54741 || || 1415150013
|-
| DFG HE 1356/70-2 (Heber) || 7458225 || 1519 || 54741 || || 1415150000
|-
| || || || || ||
|-
| 73er Titel || 0610006 || 1519 || 54740 || FuL || 1415150000
|-
| 72er Titel || 8063141 || 1519 || 54741 || || 1415150000
|}

Additionally, on the form containing the KLR data you need to specify the following:

* KLR-Verfahren: FAUKLR
* Buchungskreis: 0001
* Kostenstelle: see above
* Kostenart: 685000
* KLR Info 1: see above, leave empty if no info is given above
* KLR Info 2: your Zahlungspartner Nummer, as obtained from the idm

All other fields should be left empty.

== English information ==

Here are some PDFs you might find helpful to navigate through the German landscape of bureaucracy.

Some [[:Media:Additional_information_BayRMS.pdf|additional information]] in Englisch

The [[:Media:Bayrms_eng_data_protection.pdf|data protection waiver]] (you still have to sign the German one!)

The [[:Media:Bayrms_eng_introduction_slides.pdf|introduction slides]]

A [[:Media:Bayrms_glossary.pdf|glossary]] to match English and German terms. (REALLY HELPFUL, CONTAINS INFORMATION TO INSERT)

== ''OUTDATED!'' Business and private travels ==

If you intend to combine a business trip with a vacation to save money or just because of the occasion, you need to observe a couple of issues:

* first of all, combining business and private travel is in principle nothing that the university likes
* you *need* to get the private travel authorized on the travel request form, i.e. you need to state *both* on travel request form
* obviously you will not get any reimbursement for the private part of your trip, or any extra expenses arising from your vacation
* to get reimbursement for your business part of the trip, you need to document what the business part alone would have cost. In detail this means that you need to document:
* fictitious cost of flights/train tickets/rental car/etc for the business part of the trip
* fictitious cost of flights/train tickets/etc to and from the business destination of the trip
* nevertheless you also obviously need to state your actual cost (flight tickets etc).
* the university will reimburse you only the *lesser* of your actual cost and the fictitious cost!\\ This means that if your flight would have cost 1000 Eur, but because you stayed longer for private reasons (i.e. over the weekend) and the actual flight is cheaper like 700 Eur, the university will only reimburse you 700 Eur.

Furthermore apart from the reimbursement by the university, you have also to consider the taxes: the fiscal authorities might consider such a combination of business and private trip entirely private and therefore the reimbursement as additional income. So far,
this has never happened in Bamberg to Jörns knowledge, but in principle tax
regulations state that for a trip to count as a business trip, the
business portion must outbalance the private portion. To give an
example: a 3d observing run in Australia followed by a 2 week vacation
there would probably not be seen as a business related trip (even if it
was!), even though the university would reimburse you for your flights
and the 3d per diem.
((Based on a FAQ Email sent by Jörn to allusers on April 4, 2011))

Travel

2025-05-23T10:17:39Z

Wilms: /* List of project funds */

[[Category:Internal]]

This page documents how to apply for business travel and hand in the reimbursement with the online tool accessible through [https://www.mitarbeiterservice.bayern.de/ authega]. This requires you to have an account set up. If you sign up for the first time you will be send a letter (! yes, physical letter, this can take some days) with information for the login. For further logins it is best to use a certificate file with a password.

Once logged in you can access the travel management (Reisekostenmanagement, RMS) and enter the necessary information there. Certain numbers are tied to the observatory and will always be the same, they are documented below. '''Note:''' When selecting the institution (Beschäftigungsbehöde) do '''not''' use the Remeis-Observatory or any other smaller body. Instead use the general FAU entry with the number '''1519016'''!

More information for the general setup are in the [[:Media:introduction_bayrms.pdf|introductory slides]] (this is the German version, see below for additional guidance in English).

In order to receive documents per email you need to sign the [[:Media:Bayrms_data_protection.pdf|data protection waiver]] (in German!) and hand it in (in paper form!).

== Application for business travel ==

Some notes on filling in these forms:

=== Travel days (Reisetage) ===
On each day, you need to input the start and end of your "business".
If you are, say attending a conference starting Monday at 2 PM and ending on a Friday at noon, your times should look like this:
* Monday: Start at 14:00, end at '''23:59'''
* Tue-Thur: Start at '''0:00''', end at '''23:59'''
* Fri: Start at '''0:00''', end at 12:00

The point here being that you are still there "on business" even outside the main conference hours. Weekends are also part of the trip, if the conference is more than one week long, so this is not "private time" in this form ((c) - Joern)

(NB: There are still discussions between the administration and Joern about this)

=== Meals ===
If food is provided by hotel/conference and you do not pay for it extra - make the corresponding mark in the day

=== Mitzeichner (Signatory, in the very end of the form) ===
This needs to be your boss, who will then forward it to P6.

=== Mitreisende ===
Only employees of Bavaria (e.g., if you drive from work with someone)

=== Hotel costs ===
It is good if you have some proof why you have taken this particular option. Get some documentation (e.g., print web-page with costs) at the moment of booking, which would display other possible options in this hotel or in other hotels around.

If you travel with family, you will not be reimbursed for the difference between the single room and the room you've taken (e.g., double), so you need to document the difference of the room cost AT THE TIME OF BOOKING.

If you are staying somewhere without having to pay, choose "unentgeltliche Uebernachtung".

=== Reimbursement in advance ===
According to Edith, reimbursement in advance requires entering a remark at the end of the form, i.e., state how much you would like to get reimbursed and put this in
the remarks field. As a rule of thumb, this should not include per diems and the like, but can include travel and accommodation costs.

After approval, print the summary and give it to Edith.

== Handing in reimbursement ==

== List of project funds ==

Below is a list of project funds that you travel might be paid from. '''Before submitting your reimbursement form ask your supervisor what project to use! Every time!'''

{| class="wikitable" style="margin:auto"
|+ Project numbers
|-
! Name !! Erweiterung !! Kapitel !! Titel !! Info 1 (AWK) !! Kostenstelle
|-
| DLR 50 OR 2309 (VF-ULX) || 7401171 || 1519 || 54741 || || 1415151100
|-
| DLR 50 OO 2417 (THESEUS) || 7401182 || 1519 || 54741 || || 1415151100
|-
| DLR 50 OR 2410 (VF-XMM Aafia) || 7401186 || 1519 || 54741 || || 1415151100
|-
| DLR 50 QR 2503 (eROSITA) || 7401188 || 1519 || 54741 || || 1415151100
|-
| DLR 50 QR 2508 (ATHENA) || 7401191 || 1519 || 54741 || || 1415151100
|-
| DLR 50 OO 2507 (AXIS) || 7401196 || 1519 || 54741 || || 1415151100
|-
| || || || || ||
|-
| DFG WI 1860/19-1 (eRO STEP 1, P6) || 7458046 || 1519 || 54741 || || 1415151100
|-
| DFG WI 1860/20-1 (FOR 5195, P2) || 7458065 || 1519 || 54741 || || 1415151100
|-
| DFG WI 1860/17-2 (eRO STEP 2, P5) || 7458208 || 1519 || 54741 || || 1415151100
|-
| DFG WI 1860/21-1 (eRO STEP 2, P7) || 7458209 || 1518 || 54741 || || 1415151100
|-
| || || || || ||
|-
| DFG overhead WI until 2022 || 5002344 || 1519 || 54740 || PPS || 1415151100
|-
| DFG overhead WI from 2023 || 0150234 || 1519 || 54740 || PPS || 1415151100
|-
| || || || || ||
|-
| ESA (DALI) || 7402745 || 1519 || 54741 || || 1415151100
|-
| Wlms Altprojekte || 7402304 || 1519 || 54741 || || 1415151100
|-
| ETI Förderung || 5500245 || 1519 || 54741 || || 1415151100
|-
| || || || || ||
|-
| DFG SA 2131/13-2 (eRO STEP 2, P1) || 7458204 || 1519 || 54741 || || 1415150013
|-
| DFG SA 2131/14-2 (eRO STEP 2, P2) || 7458205 || 1519 || 54741 || || 1415150013
|-
| DFG SA 2131/15-2 (eRO STEP 2, TP Z) || 7458206 || 1519 || 54741 || || 1415150013
|-
| DFG SA 2131/18-1 (eROSITA Galaxien) || 7458168 || 1519 || 54741 || || 1415150013
|-
| || || || || ||
|-
| DFG overhead SA (Altprojekte) || 7459704 || 1519 || 54741 || || 1415150013
|-
| DFG overhead SA bis 2022 || 5002391 || 1519 || 54740 || PPS || 1415150013
|-
| DFG overhead SA ab 2023 || 0150178 || 1519 || 54740 || PPS || 1415150013
|-
| || || || || ||
|-
| DFG SA 4388/2-1 (Saeedi) || 7458207 || 1519 || 54741 || || 1415150013
|-
| DFG MA 11073/1-1 (Mayer) || 7458221 || 1519 || 54741 || || 1415150013
|-
| DFG HE 1356/70-2 (Heber) || 7458225 || 1519 || 54741 || || 1415150000
|-
| || || || || ||
|-
| 73er Titel || 0610006 || 1519 || 54740 || FuL || 1415150000
|-
| 72er Titel || 8063141 || 1519 || 54741 || || 1415150000
|}

Additionally, on the form containing the KLR data you need to specify the following:

* KLR-Verfahren: FAUKLR
* Buchungskreis: 0001
* Kostenstelle: see above
* Kostenart: 685000
* KLR Info 1: see above, leave empty if no info is given above
* KLR Info 2: your Zahlungspartner Nummer, as obtained from the idm

== English information ==

Here are some PDFs you might find helpful to navigate through the German landscape of bureaucracy.

Some [[:Media:Additional_information_BayRMS.pdf|additional information]] in Englisch

The [[:Media:Bayrms_eng_data_protection.pdf|data protection waiver]] (you still have to sign the German one!)

The [[:Media:Bayrms_eng_introduction_slides.pdf|introduction slides]]

A [[:Media:Bayrms_glossary.pdf|glossary]] to match English and German terms. (REALLY HELPFUL, CONTAINS INFORMATION TO INSERT)

== ''OUTDATED!'' Business and private travels ==

If you intend to combine a business trip with a vacation to save money or just because of the occasion, you need to observe a couple of issues:

* first of all, combining business and private travel is in principle nothing that the university likes
* you *need* to get the private travel authorized on the travel request form, i.e. you need to state *both* on travel request form
* obviously you will not get any reimbursement for the private part of your trip, or any extra expenses arising from your vacation
* to get reimbursement for your business part of the trip, you need to document what the business part alone would have cost. In detail this means that you need to document:
* fictitious cost of flights/train tickets/rental car/etc for the business part of the trip
* fictitious cost of flights/train tickets/etc to and from the business destination of the trip
* nevertheless you also obviously need to state your actual cost (flight tickets etc).
* the university will reimburse you only the *lesser* of your actual cost and the fictitious cost!\\ This means that if your flight would have cost 1000 Eur, but because you stayed longer for private reasons (i.e. over the weekend) and the actual flight is cheaper like 700 Eur, the university will only reimburse you 700 Eur.

Furthermore apart from the reimbursement by the university, you have also to consider the taxes: the fiscal authorities might consider such a combination of business and private trip entirely private and therefore the reimbursement as additional income. So far,
this has never happened in Bamberg to Jörns knowledge, but in principle tax
regulations state that for a trip to count as a business trip, the
business portion must outbalance the private portion. To give an
example: a 3d observing run in Australia followed by a 2 week vacation
there would probably not be seen as a business related trip (even if it
was!), even though the university would reimburse you for your flights
and the 3d per diem.
((Based on a FAQ Email sent by Jörn to allusers on April 4, 2011))

Travel

2025-05-23T10:15:09Z

Wilms: /* List of project funds */

[[Category:Internal]]

This page documents how to apply for business travel and hand in the reimbursement with the online tool accessible through [https://www.mitarbeiterservice.bayern.de/ authega]. This requires you to have an account set up. If you sign up for the first time you will be send a letter (! yes, physical letter, this can take some days) with information for the login. For further logins it is best to use a certificate file with a password.

Once logged in you can access the travel management (Reisekostenmanagement, RMS) and enter the necessary information there. Certain numbers are tied to the observatory and will always be the same, they are documented below. '''Note:''' When selecting the institution (Beschäftigungsbehöde) do '''not''' use the Remeis-Observatory or any other smaller body. Instead use the general FAU entry with the number '''1519016'''!

More information for the general setup are in the [[:Media:introduction_bayrms.pdf|introductory slides]] (this is the German version, see below for additional guidance in English).

In order to receive documents per email you need to sign the [[:Media:Bayrms_data_protection.pdf|data protection waiver]] (in German!) and hand it in (in paper form!).

== Application for business travel ==

Some notes on filling in these forms:

=== Travel days (Reisetage) ===
On each day, you need to input the start and end of your "business".
If you are, say attending a conference starting Monday at 2 PM and ending on a Friday at noon, your times should look like this:
* Monday: Start at 14:00, end at '''23:59'''
* Tue-Thur: Start at '''0:00''', end at '''23:59'''
* Fri: Start at '''0:00''', end at 12:00

The point here being that you are still there "on business" even outside the main conference hours. Weekends are also part of the trip, if the conference is more than one week long, so this is not "private time" in this form ((c) - Joern)

(NB: There are still discussions between the administration and Joern about this)

=== Meals ===
If food is provided by hotel/conference and you do not pay for it extra - make the corresponding mark in the day

=== Mitzeichner (Signatory, in the very end of the form) ===
This needs to be your boss, who will then forward it to P6.

=== Mitreisende ===
Only employees of Bavaria (e.g., if you drive from work with someone)

=== Hotel costs ===
It is good if you have some proof why you have taken this particular option. Get some documentation (e.g., print web-page with costs) at the moment of booking, which would display other possible options in this hotel or in other hotels around.

If you travel with family, you will not be reimbursed for the difference between the single room and the room you've taken (e.g., double), so you need to document the difference of the room cost AT THE TIME OF BOOKING.

If you are staying somewhere without having to pay, choose "unentgeltliche Uebernachtung".

=== Reimbursement in advance ===
According to Edith, reimbursement in advance requires entering a remark at the end of the form, i.e., state how much you would like to get reimbursed and put this in
the remarks field. As a rule of thumb, this should not include per diems and the like, but can include travel and accommodation costs.

After approval, print the summary and give it to Edith.

== Handing in reimbursement ==

== List of project funds ==

Below is a list of project funds that you travel might be paid from. '''Before submitting your reimbursement form ask your supervisor what project to use! Every time!'''

{| class="wikitable" style="margin:auto"
|+ Project numbers
|-
! Name !! Erweiterung !! Kapitel !! Titel !! Info 1 (AWK) !! Kostenstelle
|-
| DLR 50 OR 2309 (VF-ULX) || 7401171 || 1519 || 54741 || || 1415151100
|-
| DLR 50 OO 2417 (THESEUS) || 7401182 || 1519 || 54741 || || 1415151100
|-
| DLR 50 OR 2410 (VF-XMM Aafia) || 7401186 || 1519 || 54741 || || 1415151100
|-
| DLR 50 QR 2503 (eROSITA) || 7401188 || 1519 || 54741 || || 1415151100
|-
| DLR 50 QR 2508 (ATHENA) || 7401191 || 1519 || 54741 || || 1415151100
|-
| DLR 50 OO 2507 (AXIS) || 7401196 || 1519 || 54741 || || 1415151100
|-
| || || || || ||
|-
| DFG WI 1860/19-1 (eRO STEP 1, P6) || 7458046 || 1519 || 54741 || || 1415151100
|-
| DFG WI 1860/20-1 (FOR 5195, P2) || 7458065 || 1519 || 54741 || || 1415151100
|-
| DFG WI 1860/17-2 (eRO STEP 2, P5) || 7458208 || 1519 || 54741 || || 1415151100
|-
| DFG WI 1860/21-1 (eRO STEP 2, P7) || 7458209 || 1518 || 54741 || || 1415151100
|-
| || || || || ||
|-
| DFG overhead WI until 2022 || 5002344 || 1519 || 54740 || PPS || 1415151100
|-
| DFG overhead WI from 2023 || 0150234 || 1519 || 54740 || PPS || 1415151100
|-
| || || || || ||
|-
| ESA (DALI) || 7402745 || 1519 || 54741 || || 1415151100
|-
| Wlms Altprojekte || 7402304 || 1519 || 54741 || || 1415151100
|-
| ETI Förderung || 5500245 || 1519 || 54741 || || 1415151100
|-
| || || || || ||
|-
| DFG SA 2131/13-2 (eRO STEP 2, P1) || 7458204 || 1519 || 54741 || || 1415150013
|-
| DFG SA 2131/14-2 (eRO STEP 2, P2) || 7458205 || 1519 || 54741 || || 1415150013
|-
| DFG SA 2131/15-2 (eRO STEP 2, TP Z) || 7458206 || 1519 || 54741 || || 1415150013
|-
| DFG SA 2131/18-1 (eROSITA Galaxien) || 7458168 || 1519 || 54741 || || 1415150013
|-
| || || || || ||
|-
| DFG overhead SA (Altprojekte) || 7459704 || 1519 || 54741 || || 1415150013
|-
| DFG overhead SA bis 2022 || 5002391 || 1519 || 54740 || PPS || 1415150013
|-
| DFG overhead SA ab 2023 || 0150178 || 1519 || 54740 || PPS || 1415150013
|-
| || || || || ||
|-
| DFG SA 4388/2-1 (Saeedi) || 7458207 || 1519 || 54741 || || 1415150013
|-
| DFG MA 11073/1-1 (Mayer) || 7458221 || 1519 || 54741 || || 1415150013
|-
| DFG HE 1356/70-2 (Heber) || 7458225 || 1519 || 54741 || || 1415150000
|-
| || || || || ||
|-
| 73er Titel || 061 000-6 || 1519 || 54740 || FuL || 1415150000
|-
| 72er Titel || 806 3141 || 1519 || 54741 || || 1415150000
|}

Additionally, on the form containing the KLR data you need to specify the following:

* KLR-Verfahren: FAUKLR
* Buchungskreis: 0001
* Kostenstelle: see above
* Kostenart: 685000
* KLR Info 1: see above, leave empty if no info is given above
* KLR Info 2: your Zahlungspartner Nummer, as obtained from the idm

== English information ==

Here are some PDFs you might find helpful to navigate through the German landscape of bureaucracy.

Some [[:Media:Additional_information_BayRMS.pdf|additional information]] in Englisch

The [[:Media:Bayrms_eng_data_protection.pdf|data protection waiver]] (you still have to sign the German one!)

The [[:Media:Bayrms_eng_introduction_slides.pdf|introduction slides]]

A [[:Media:Bayrms_glossary.pdf|glossary]] to match English and German terms. (REALLY HELPFUL, CONTAINS INFORMATION TO INSERT)

== ''OUTDATED!'' Business and private travels ==

If you intend to combine a business trip with a vacation to save money or just because of the occasion, you need to observe a couple of issues:

* first of all, combining business and private travel is in principle nothing that the university likes
* you *need* to get the private travel authorized on the travel request form, i.e. you need to state *both* on travel request form
* obviously you will not get any reimbursement for the private part of your trip, or any extra expenses arising from your vacation
* to get reimbursement for your business part of the trip, you need to document what the business part alone would have cost. In detail this means that you need to document:
* fictitious cost of flights/train tickets/rental car/etc for the business part of the trip
* fictitious cost of flights/train tickets/etc to and from the business destination of the trip
* nevertheless you also obviously need to state your actual cost (flight tickets etc).
* the university will reimburse you only the *lesser* of your actual cost and the fictitious cost!\\ This means that if your flight would have cost 1000 Eur, but because you stayed longer for private reasons (i.e. over the weekend) and the actual flight is cheaper like 700 Eur, the university will only reimburse you 700 Eur.

Furthermore apart from the reimbursement by the university, you have also to consider the taxes: the fiscal authorities might consider such a combination of business and private trip entirely private and therefore the reimbursement as additional income. So far,
this has never happened in Bamberg to Jörns knowledge, but in principle tax
regulations state that for a trip to count as a business trip, the
business portion must outbalance the private portion. To give an
example: a 3d observing run in Australia followed by a 2 week vacation
there would probably not be seen as a business related trip (even if it
was!), even though the university would reimburse you for your flights
and the 3d per diem.
((Based on a FAQ Email sent by Jörn to allusers on April 4, 2011))

Travel

2025-05-23T10:13:38Z

Wilms: /* List of project funds */

[[Category:Internal]]

This page documents how to apply for business travel and hand in the reimbursement with the online tool accessible through [https://www.mitarbeiterservice.bayern.de/ authega]. This requires you to have an account set up. If you sign up for the first time you will be send a letter (! yes, physical letter, this can take some days) with information for the login. For further logins it is best to use a certificate file with a password.

Once logged in you can access the travel management (Reisekostenmanagement, RMS) and enter the necessary information there. Certain numbers are tied to the observatory and will always be the same, they are documented below. '''Note:''' When selecting the institution (Beschäftigungsbehöde) do '''not''' use the Remeis-Observatory or any other smaller body. Instead use the general FAU entry with the number '''1519016'''!

More information for the general setup are in the [[:Media:introduction_bayrms.pdf|introductory slides]] (this is the German version, see below for additional guidance in English).

In order to receive documents per email you need to sign the [[:Media:Bayrms_data_protection.pdf|data protection waiver]] (in German!) and hand it in (in paper form!).

== Application for business travel ==

Some notes on filling in these forms:

=== Travel days (Reisetage) ===
On each day, you need to input the start and end of your "business".
If you are, say attending a conference starting Monday at 2 PM and ending on a Friday at noon, your times should look like this:
* Monday: Start at 14:00, end at '''23:59'''
* Tue-Thur: Start at '''0:00''', end at '''23:59'''
* Fri: Start at '''0:00''', end at 12:00

The point here being that you are still there "on business" even outside the main conference hours. Weekends are also part of the trip, if the conference is more than one week long, so this is not "private time" in this form ((c) - Joern)

(NB: There are still discussions between the administration and Joern about this)

=== Meals ===
If food is provided by hotel/conference and you do not pay for it extra - make the corresponding mark in the day

=== Mitzeichner (Signatory, in the very end of the form) ===
This needs to be your boss, who will then forward it to P6.

=== Mitreisende ===
Only employees of Bavaria (e.g., if you drive from work with someone)

=== Hotel costs ===
It is good if you have some proof why you have taken this particular option. Get some documentation (e.g., print web-page with costs) at the moment of booking, which would display other possible options in this hotel or in other hotels around.

If you travel with family, you will not be reimbursed for the difference between the single room and the room you've taken (e.g., double), so you need to document the difference of the room cost AT THE TIME OF BOOKING.

If you are staying somewhere without having to pay, choose "unentgeltliche Uebernachtung".

=== Reimbursement in advance ===
According to Edith, reimbursement in advance requires entering a remark at the end of the form, i.e., state how much you would like to get reimbursed and put this in
the remarks field. As a rule of thumb, this should not include per diems and the like, but can include travel and accommodation costs.

After approval, print the summary and give it to Edith.

== Handing in reimbursement ==

== List of project funds ==

Below is a list of project funds that you travel might be paid from. '''Before submitting your reimbursement form ask your supervisor what project to use! Every time!'''

{| class="wikitable" style="margin:auto"
|+ Project numbers
|-
! Name !! Erweiterung !! Kapitel !! Titel !! Info 1 (AWK) !! Kostenstelle
|-
| DLR 50 OR 2309 (VF-ULX) || 7401171 || 1519 || 54741 || || 1415151100
|-
| DLR 50 OO 2417 (THESEUS) || 7401182 || 1519 || 54741 || || 1415151100
|-
| DLR 50 OR 2410 (VF-XMM Aafia) || 7401186 || 1519 || 54741 || || 1415151100
|-
| DLR 50 QR 2503 (eROSITA) || 7401188 || 1519 || 54741 || || 1415151100
|-
| DLR 50 QR 2508 (ATHENA) || 7401191 || 1519 || 54741 || || 1415151100
|-
| DLR 50 OO 2507 (AXIS) || 7401196 || 1519 || 54741 || || 1415151100
|-
| || || || || ||
|-
| DFG WI 1860/19-1 (eRO STEP 1, P6) || 7458046 || 1519 || 54741 || || 1415151100
|-
| DFG WI 1860/20-1 (FOR 5195, P2) || 7458065 || 1519 || 54741 || || 1415151100
|-
| DFG WI 1860/17-2 (eRO STEP 2, P5) || 7458208 || 1519 || 54741 || || 1415151100
|-
| DFG WI 1860/21-1 (eRO STEP 2, P7) || 7458209 || 1518 || 54741 || || 1415151100
|-
| || || || || ||
|-
| DFG overhead WI until 2022 || 5002344 || 1519 || 54740 || PPS || 1415151100
|-
| DFG overhead WI from 2023 || 150234 || 1519 || 54740 || PPS || 1415151100
|-
| || || || || ||
|-
| ESA (DALI) || 7402 745 || 1519 || 54741 || || 1415151100
|-
| Wlms Altprojekte || 7402 304 || 1519 || 54741 || || 1415151100
|-
| ETI Förderung || 5500 245 || 1519 || 54741 || || 1415151100
|-
| || || || || ||
|-
| DFG SA 2131/13-2 (eRO STEP 2, P1) || 7458204 || 1519 || 54741 || || 1415150013
|-
| DFG SA 2131/14-2 (eRO STEP 2, P2) || 7458205 || 1519 || 54741 || || 1415150013
|-
| DFG SA 2131/15-2 (eRO STEP 2, TP Z) || 7458206 || 1519 || 54741 || || 1415150013
|-
| DFG SA 2131/18-1 (eROSITA Galaxien) || 7458168 || 1519 || 54741 || || 1415150013
|-
| || || || || ||
|-
| DFG overhead SA (Altprojekte) || 7459704 || 1519 || 54741 || || 1415150013
|-
| DFG overhead SA bis 2022 || 5002391 || 1519 || 54740 || PPS || 1415150013
|-
| DFG overhead SA ab 2023 || 0150178 || 1519 || 54740 || PPS || 1415150013
|-
| || || || || ||
|-
| DFG SA 4388/2-1 (Saeedi) || 7458207 || 1519 || 54741 || || 1415150013
|-
| DFG MA 11073/1-1 (Mayer) || 7458221 || 1519 || 54741 || || 1415150013
|-
| DFG HE 1356/70-2 (Heber) || 7458225 || 1519 || 54741 || || 1415150000
|-
| || || || || ||
|-
| 73er Titel || 061 000-6 || 1519 || 54740 || FuL || 1415150000
|-
| 72er Titel || 806 3141 || 1519 || 54741 || || 1415150000
|}

Additionally, on the form containing the KLR data you need to specify the following:

* KLR-Verfahren: FAUKLR
* Buchungskreis: 0001
* Kostenstelle: see above
* Kostenart: 685000
* KLR Info 1: see above, leave empty if no info is given above
* KLR Info 2: your Zahlungspartner Nummer, as obtained from the idm

== English information ==

Here are some PDFs you might find helpful to navigate through the German landscape of bureaucracy.

Some [[:Media:Additional_information_BayRMS.pdf|additional information]] in Englisch

The [[:Media:Bayrms_eng_data_protection.pdf|data protection waiver]] (you still have to sign the German one!)

The [[:Media:Bayrms_eng_introduction_slides.pdf|introduction slides]]

A [[:Media:Bayrms_glossary.pdf|glossary]] to match English and German terms. (REALLY HELPFUL, CONTAINS INFORMATION TO INSERT)

== ''OUTDATED!'' Business and private travels ==

If you intend to combine a business trip with a vacation to save money or just because of the occasion, you need to observe a couple of issues:

* first of all, combining business and private travel is in principle nothing that the university likes
* you *need* to get the private travel authorized on the travel request form, i.e. you need to state *both* on travel request form
* obviously you will not get any reimbursement for the private part of your trip, or any extra expenses arising from your vacation
* to get reimbursement for your business part of the trip, you need to document what the business part alone would have cost. In detail this means that you need to document:
* fictitious cost of flights/train tickets/rental car/etc for the business part of the trip
* fictitious cost of flights/train tickets/etc to and from the business destination of the trip
* nevertheless you also obviously need to state your actual cost (flight tickets etc).
* the university will reimburse you only the *lesser* of your actual cost and the fictitious cost!\\ This means that if your flight would have cost 1000 Eur, but because you stayed longer for private reasons (i.e. over the weekend) and the actual flight is cheaper like 700 Eur, the university will only reimburse you 700 Eur.

Furthermore apart from the reimbursement by the university, you have also to consider the taxes: the fiscal authorities might consider such a combination of business and private trip entirely private and therefore the reimbursement as additional income. So far,
this has never happened in Bamberg to Jörns knowledge, but in principle tax
regulations state that for a trip to count as a business trip, the
business portion must outbalance the private portion. To give an
example: a 3d observing run in Australia followed by a 2 week vacation
there would probably not be seen as a business related trip (even if it
was!), even though the university would reimburse you for your flights
and the 3d per diem.
((Based on a FAQ Email sent by Jörn to allusers on April 4, 2011))

Travel

2025-05-23T09:55:05Z

Wilms: /* List of project funds */

[[Category:Internal]]

This page documents how to apply for business travel and hand in the reimbursement with the online tool accessible through [https://www.mitarbeiterservice.bayern.de/ authega]. This requires you to have an account set up. If you sign up for the first time you will be send a letter (! yes, physical letter, this can take some days) with information for the login. For further logins it is best to use a certificate file with a password.

Once logged in you can access the travel management (Reisekostenmanagement, RMS) and enter the necessary information there. Certain numbers are tied to the observatory and will always be the same, they are documented below. '''Note:''' When selecting the institution (Beschäftigungsbehöde) do '''not''' use the Remeis-Observatory or any other smaller body. Instead use the general FAU entry with the number '''1519016'''!

More information for the general setup are in the [[:Media:introduction_bayrms.pdf|introductory slides]] (this is the German version, see below for additional guidance in English).

In order to receive documents per email you need to sign the [[:Media:Bayrms_data_protection.pdf|data protection waiver]] (in German!) and hand it in (in paper form!).

== Application for business travel ==

Some notes on filling in these forms:

=== Travel days (Reisetage) ===
On each day, you need to input the start and end of your "business".
If you are, say attending a conference starting Monday at 2 PM and ending on a Friday at noon, your times should look like this:
* Monday: Start at 14:00, end at '''23:59'''
* Tue-Thur: Start at '''0:00''', end at '''23:59'''
* Fri: Start at '''0:00''', end at 12:00

The point here being that you are still there "on business" even outside the main conference hours. Weekends are also part of the trip, if the conference is more than one week long, so this is not "private time" in this form ((c) - Joern)

(NB: There are still discussions between the administration and Joern about this)

=== Meals ===
If food is provided by hotel/conference and you do not pay for it extra - make the corresponding mark in the day

=== Mitzeichner (Signatory, in the very end of the form) ===
This needs to be your boss, who will then forward it to P6.

=== Mitreisende ===
Only employees of Bavaria (e.g., if you drive from work with someone)

=== Hotel costs ===
It is good if you have some proof why you have taken this particular option. Get some documentation (e.g., print web-page with costs) at the moment of booking, which would display other possible options in this hotel or in other hotels around.

If you travel with family, you will not be reimbursed for the difference between the single room and the room you've taken (e.g., double), so you need to document the difference of the room cost AT THE TIME OF BOOKING.

If you are staying somewhere without having to pay, choose "unentgeltliche Uebernachtung".

=== Reimbursement in advance ===
According to Edith, reimbursement in advance requires entering a remark at the end of the form, i.e., state how much you would like to get reimbursed and put this in
the remarks field. As a rule of thumb, this should not include per diems and the like, but can include travel and accommodation costs.

After approval, print the summary and give it to Edith.

== Handing in reimbursement ==

== List of project funds ==

Below is a list of project funds that you travel might be paid from. '''Before submitting your reimbursement form ask your supervisor what project to use! Every time!'''

{| class="wikitable" style="margin:auto"
|+ Project numbers
|-
! Name !! Erweiterung !! Kapitel !! Titel !! Info 1 (AWK) !! Kostenstelle
|-
| DLR 50 OR 2309 (VF-ULX) || 7401171 || 1519 || 54741 || || 1415151100
|-
| DLR 50 OO 2417 (THESEUS) || 7401182 || 1519 || 54741 || || 1415151100
|-
| DLR 50 OR 2410 (VF-XMM Aafia) || 7401186 || 1519 || 54741 || || 1415151100
|-
| DLR 50 QR 2503 (eROSITA) || 7401188 || 1519 || 54741 || || 1415151100
|-
| DLR 50 QR 2508 (ATHENA) || 7401191 || 1519 || 54741 || || 1415151100
|-
| DLR 50 OO 2507 (AXIS) || 7401196 || 1519 || 54741 || || 1415151100
|-
| || || || || ||
|-
| DFG WI 1860/17-2 (eRO STEP 1, P5) || 7458208 || 1519 || 54741 || || 1415151100
|-
| DFG WI 1860/19-1 (eRO STEP 1, P6) || 7458046 || 1519 || 54741 || || 1415151100
|-
| DFG WI 1860/20-1 (FOR 5195, P2) || 7458065 || 1519 || 54741 || || 1415151100
|-
| DFG WI 1860/21-1 (eRO STEP 2, P7) || 7458209 || 1518 || 54741 || || 1415151100
|-
| || || || || ||
|-
| DFG overhead WI until 2022 || 5002344 || 1519 || 54740 || PPS || 1415151100
|-
| DFG overhead WI from 2023 || 150234 || 1519 || 54740 || PPS || 1415151100
|-
| || || || || ||
|-
| ESA (DALI) || 7402 745 || 1519 || 54741 || || 1415151100
|-
| Wlms Altprojekte || 7402 304 || 1519 || 54741 || || 1415151100
|-
| ETI Förderung || 5500 245 || 1519 || 54741 || || 1415151100
|-
| || || || || ||
|-
| DFG SA 2131/13-2 (eRO STEP 2, P1) || 7458204 || 1519 || 54741 || || 1415150013
|-
| DFG SA 2131/14-2 (eRO STEP 2, P2) || 7458205 || 1519 || 54741 || || 1415150013
|-
| DFG SA 2131/15-2 (eRO STEP 2, TP Z) || 7458206 || 1519 || 54741 || || 1415150013
|-
| DFG SA 2131/18-1 (eROSITA Galaxien) || 7458168 || 1519 || 54741 || || 1415150013
|-
| || || || || ||
|-
| DFG overhead SA (Altprojekte) || 7459704 || 1519 || 54741 || || 1415150013
|-
| DFG overhead SA bis 2022 || 5002391 || 1519 || 54740 || PPS || 1415150013
|-
| DFG overhead SA ab 2023 || 0150178 || 1519 || 54740 || PPS || 1415150013
|-
| || || || || ||
|-
| DFG SA 4388/2-1 (Saeedi) || 7458207 || 1519 || 54741 || || 1415150013
|-
| DFG MA 11073/1-1 (Mayer) || 7458221 || 1519 || 54741 || || 1415150013
|-
| DFG HE 1356/70-2 (Heber) || 7458225 || 1519 || 54741 || || 1415150000
|-
| || || || || ||
|-
| 73er Titel || 061 000-6 || 1519 || 54740 || FuL || 1415150000
|-
| 72er Titel || 806 3141 || 1519 || 54741 || || 1415150000
|}

If the AWK is empty in the table above, do not put anything in the '''Info 1''' field. Otherwise add the given abbreviation.

Additionally, on the form where you are entering the KLR data you need to specify the following:

* KLR-Verfahren: FAUKLR
* Buchungskreis: 0001
* Kostenstelle: see above
* Kostenart: 685000
* KLR Info 1: see above, leave empty if no info is given above
* KLR Info 2: your Zahlungspartner Nummer, as obtained from the idm

== English information ==

Here are some PDFs you might find helpful to navigate through the German landscape of bureaucracy.

Some [[:Media:Additional_information_BayRMS.pdf|additional information]] in Englisch

The [[:Media:Bayrms_eng_data_protection.pdf|data protection waiver]] (you still have to sign the German one!)

The [[:Media:Bayrms_eng_introduction_slides.pdf|introduction slides]]

A [[:Media:Bayrms_glossary.pdf|glossary]] to match English and German terms. (REALLY HELPFUL, CONTAINS INFORMATION TO INSERT)

== ''OUTDATED!'' Business and private travels ==

If you intend to combine a business trip with a vacation to save money or just because of the occasion, you need to observe a couple of issues:

* first of all, combining business and private travel is in principle nothing that the university likes
* you *need* to get the private travel authorized on the travel request form, i.e. you need to state *both* on travel request form
* obviously you will not get any reimbursement for the private part of your trip, or any extra expenses arising from your vacation
* to get reimbursement for your business part of the trip, you need to document what the business part alone would have cost. In detail this means that you need to document:
* fictitious cost of flights/train tickets/rental car/etc for the business part of the trip
* fictitious cost of flights/train tickets/etc to and from the business destination of the trip
* nevertheless you also obviously need to state your actual cost (flight tickets etc).
* the university will reimburse you only the *lesser* of your actual cost and the fictitious cost!\\ This means that if your flight would have cost 1000 Eur, but because you stayed longer for private reasons (i.e. over the weekend) and the actual flight is cheaper like 700 Eur, the university will only reimburse you 700 Eur.

Furthermore apart from the reimbursement by the university, you have also to consider the taxes: the fiscal authorities might consider such a combination of business and private trip entirely private and therefore the reimbursement as additional income. So far,
this has never happened in Bamberg to Jörns knowledge, but in principle tax
regulations state that for a trip to count as a business trip, the
business portion must outbalance the private portion. To give an
example: a 3d observing run in Australia followed by a 2 week vacation
there would probably not be seen as a business related trip (even if it
was!), even though the university would reimburse you for your flights
and the 3d per diem.
((Based on a FAQ Email sent by Jörn to allusers on April 4, 2011))

Travel

2025-05-23T09:49:53Z

Wilms: /* Reimbursement in advance */

[[Category:Internal]]

This page documents how to apply for business travel and hand in the reimbursement with the online tool accessible through [https://www.mitarbeiterservice.bayern.de/ authega]. This requires you to have an account set up. If you sign up for the first time you will be send a letter (! yes, physical letter, this can take some days) with information for the login. For further logins it is best to use a certificate file with a password.

Once logged in you can access the travel management (Reisekostenmanagement, RMS) and enter the necessary information there. Certain numbers are tied to the observatory and will always be the same, they are documented below. '''Note:''' When selecting the institution (Beschäftigungsbehöde) do '''not''' use the Remeis-Observatory or any other smaller body. Instead use the general FAU entry with the number '''1519016'''!

More information for the general setup are in the [[:Media:introduction_bayrms.pdf|introductory slides]] (this is the German version, see below for additional guidance in English).

In order to receive documents per email you need to sign the [[:Media:Bayrms_data_protection.pdf|data protection waiver]] (in German!) and hand it in (in paper form!).

== Application for business travel ==

Some notes on filling in these forms:

=== Travel days (Reisetage) ===
On each day, you need to input the start and end of your "business".
If you are, say attending a conference starting Monday at 2 PM and ending on a Friday at noon, your times should look like this:
* Monday: Start at 14:00, end at '''23:59'''
* Tue-Thur: Start at '''0:00''', end at '''23:59'''
* Fri: Start at '''0:00''', end at 12:00

The point here being that you are still there "on business" even outside the main conference hours. Weekends are also part of the trip, if the conference is more than one week long, so this is not "private time" in this form ((c) - Joern)

(NB: There are still discussions between the administration and Joern about this)

=== Meals ===
If food is provided by hotel/conference and you do not pay for it extra - make the corresponding mark in the day

=== Mitzeichner (Signatory, in the very end of the form) ===
This needs to be your boss, who will then forward it to P6.

=== Mitreisende ===
Only employees of Bavaria (e.g., if you drive from work with someone)

=== Hotel costs ===
It is good if you have some proof why you have taken this particular option. Get some documentation (e.g., print web-page with costs) at the moment of booking, which would display other possible options in this hotel or in other hotels around.

If you travel with family, you will not be reimbursed for the difference between the single room and the room you've taken (e.g., double), so you need to document the difference of the room cost AT THE TIME OF BOOKING.

If you are staying somewhere without having to pay, choose "unentgeltliche Uebernachtung".

=== Reimbursement in advance ===
According to Edith, reimbursement in advance requires entering a remark at the end of the form, i.e., state how much you would like to get reimbursed and put this in
the remarks field. As a rule of thumb, this should not include per diems and the like, but can include travel and accommodation costs.

After approval, print the summary and give it to Edith.

== Handing in reimbursement ==

== List of project funds ==

Below is a list of project funds that you travel might be payed from. '''Before submitting your reimbursement form ask your supervisor what project to use! Every time!'''

{| class="wikitable" style="margin:auto"
|+ Project numbers
|-
! Name !! Erweiterung !! Kapitel !! Titel !! Info 1 (AWK) !! Kostenstelle
|-
| DLR 50 OR 2309 (VF-ULX) || 7401171 || 1519 || 54741 || || 1415151100
|-
| DLR 50 OO 2417 (THESEUS) || 7401182 || 1519 || 54741 || || 1415151100
|-
| DLR 50 OR 2410 (VF-XMM Aafia) || 7401186 || 1519 || 54741 || || 1415151100
|-
| DLR 50 QR 2503 (eROSITA) || 7401188 || 1519 || 54741 || || 1415151100
|-
| DLR 50 QR 2508 (ATHENA) || 7401191 || 1519 || 54741 || || 1415151100
|-
| DLR 50 OO 2507 (AXIS) || 7401196 || 1519 || 54741 || || 1415151100
|-
| || || || || ||
|-
| DFG WI 1860/17-2 (eRO STEP 1, P5) || 7458208 || 1519 || 54741 || || 1415151100
|-
| DFG WI 1860/19-1 (eRO STEP 1, P6) || 7458046 || 1519 || 54741 || || 1415151100
|-
| DFG WI 1860/20-1 (FOR 5195, P2) || 7458065 || 1519 || 54741 || || 1415151100
|-
| DFG WI 1860/21-1 (eRO STEP 2, P7) || 7458209 || 1518 || 54741 || || 1415151100
|-
| || || || || ||
|-
| DFG overhead WI until 2022 || 5002344 || 1519 || 54740 || PPS || 1415151100
|-
| DFG overhead WI from 2023 || 150234 || 1519 || 54740 || PPS || 1415151100
|-
| || || || || ||
|-
| ESA (DALI) || 7402 745 || 1519 || 54741 || || 1415151100
|-
| Wlms Altprojekte || 7402 304 || 1519 || 54741 || || 1415151100
|-
| ETI Förderung || 5500 245 || 1519 || 54741 || || 1415151100
|-
| || || || || ||
|-
| DFG SA 2131/13-2 (eRO STEP 2, P1) || 7458204 || 1519 || 54741 || || 1415150013
|-
| DFG SA 2131/14-2 (eRO STEP 2, P2) || 7458205 || 1519 || 54741 || || 1415150013
|-
| DFG SA 2131/15-2 (eRO STEP 2, TP Z) || 7458206 || 1519 || 54741 || || 1415150013
|-
| DFG SA 2131/18-1 (eROSITA Galaxien) || 7458168 || 1519 || 54741 || || 1415150013
|-
| || || || || ||
|-
| DFG overhead SA (Altprojekte) || 7459704 || 1519 || 54741 || || 1415150013
|-
| DFG overhead SA bis 2022 || 5002391 || 1519 || 54740 || PPS || 1415150013
|-
| DFG overhead SA ab 2023 || 0150178 || 1519 || 54740 || PPS || 1415150013
|-
| || || || || ||
|-
| DFG SA 4388/2-1 (Saeedi) || 7458207 || 1519 || 54741 || || 1415150013
|-
| DFG MA 11073/1-1 (Mayer) || 7458221 || 1519 || 54741 || || 1415150013
|-
| DFG HE 1356/70-2 (Heber) || 7458225 || 1519 || 54741 || || 1415150000
|-
| || || || || ||
|-
| 73er Titel || 061 000-6 || 1519 || 54740 || FuL || 1415150000
|-
| 72er Titel || 806 3141 || 1519 || 54741 || || 1415150000
|}

Additionally you need to specify the kind of expense (Kostenart): 685000. If the AWK is empty in the table above, do not put anything in the '''Info 1''' field. Otherwise add the given symbol.

== English information ==

Here are some PDFs you might find helpful to navigate through the German landscape of bureaucracy.

Some [[:Media:Additional_information_BayRMS.pdf|additional information]] in Englisch

The [[:Media:Bayrms_eng_data_protection.pdf|data protection waiver]] (you still have to sign the German one!)

The [[:Media:Bayrms_eng_introduction_slides.pdf|introduction slides]]

A [[:Media:Bayrms_glossary.pdf|glossary]] to match English and German terms. (REALLY HELPFUL, CONTAINS INFORMATION TO INSERT)

== ''OUTDATED!'' Business and private travels ==

If you intend to combine a business trip with a vacation to save money or just because of the occasion, you need to observe a couple of issues:

* first of all, combining business and private travel is in principle nothing that the university likes
* you *need* to get the private travel authorized on the travel request form, i.e. you need to state *both* on travel request form
* obviously you will not get any reimbursement for the private part of your trip, or any extra expenses arising from your vacation
* to get reimbursement for your business part of the trip, you need to document what the business part alone would have cost. In detail this means that you need to document:
* fictitious cost of flights/train tickets/rental car/etc for the business part of the trip
* fictitious cost of flights/train tickets/etc to and from the business destination of the trip
* nevertheless you also obviously need to state your actual cost (flight tickets etc).
* the university will reimburse you only the *lesser* of your actual cost and the fictitious cost!\\ This means that if your flight would have cost 1000 Eur, but because you stayed longer for private reasons (i.e. over the weekend) and the actual flight is cheaper like 700 Eur, the university will only reimburse you 700 Eur.

Furthermore apart from the reimbursement by the university, you have also to consider the taxes: the fiscal authorities might consider such a combination of business and private trip entirely private and therefore the reimbursement as additional income. So far,
this has never happened in Bamberg to Jörns knowledge, but in principle tax
regulations state that for a trip to count as a business trip, the
business portion must outbalance the private portion. To give an
example: a 3d observing run in Australia followed by a 2 week vacation
there would probably not be seen as a business related trip (even if it
was!), even though the university would reimburse you for your flights
and the 3d per diem.
((Based on a FAQ Email sent by Jörn to allusers on April 4, 2011))

Travel

2025-05-23T09:48:03Z

Wilms:

[[Category:Internal]]

This page documents how to apply for business travel and hand in the reimbursement with the online tool accessible through [https://www.mitarbeiterservice.bayern.de/ authega]. This requires you to have an account set up. If you sign up for the first time you will be send a letter (! yes, physical letter, this can take some days) with information for the login. For further logins it is best to use a certificate file with a password.

Once logged in you can access the travel management (Reisekostenmanagement, RMS) and enter the necessary information there. Certain numbers are tied to the observatory and will always be the same, they are documented below. '''Note:''' When selecting the institution (Beschäftigungsbehöde) do '''not''' use the Remeis-Observatory or any other smaller body. Instead use the general FAU entry with the number '''1519016'''!

More information for the general setup are in the [[:Media:introduction_bayrms.pdf|introductory slides]] (this is the German version, see below for additional guidance in English).

In order to receive documents per email you need to sign the [[:Media:Bayrms_data_protection.pdf|data protection waiver]] (in German!) and hand it in (in paper form!).

== Application for business travel ==

Some notes on filling in these forms:

=== Travel days (Reisetage) ===
On each day, you need to input the start and end of your "business".
If you are, say attending a conference starting Monday at 2 PM and ending on a Friday at noon, your times should look like this:
* Monday: Start at 14:00, end at '''23:59'''
* Tue-Thur: Start at '''0:00''', end at '''23:59'''
* Fri: Start at '''0:00''', end at 12:00

The point here being that you are still there "on business" even outside the main conference hours. Weekends are also part of the trip, if the conference is more than one week long, so this is not "private time" in this form ((c) - Joern)

(NB: There are still discussions between the administration and Joern about this)

=== Meals ===
If food is provided by hotel/conference and you do not pay for it extra - make the corresponding mark in the day

=== Mitzeichner (Signatory, in the very end of the form) ===
This needs to be your boss, who will then forward it to P6.

=== Mitreisende ===
Only employees of Bavaria (e.g., if you drive from work with someone)

=== Hotel costs ===
It is good if you have some proof why you have taken this particular option. Get some documentation (e.g., print web-page with costs) at the moment of booking, which would display other possible options in this hotel or in other hotels around.

If you travel with family, you will not be reimbursed for the difference between the single room and the room you've taken (e.g., double), so you need to document the difference of the room cost AT THE TIME OF BOOKING.

If you are staying somewhere without having to pay, choose "unentgeltliche Uebernachtung".

=== Reimbursement in advance ===
According to Edith, reimbursement in advance requires entering a remark at the end of the form, i.e. we should already have this in mind while filling out the application.

The following may be outdated: If you need to be reimbursed in advance. After approval of the trip, print the trip summary and talk to Edith.)

== Handing in reimbursement ==

== List of project funds ==

Below is a list of project funds that you travel might be payed from. '''Before submitting your reimbursement form ask your supervisor what project to use! Every time!'''

{| class="wikitable" style="margin:auto"
|+ Project numbers
|-
! Name !! Erweiterung !! Kapitel !! Titel !! Info 1 (AWK) !! Kostenstelle
|-
| DLR 50 OR 2309 (VF-ULX) || 7401171 || 1519 || 54741 || || 1415151100
|-
| DLR 50 OO 2417 (THESEUS) || 7401182 || 1519 || 54741 || || 1415151100
|-
| DLR 50 OR 2410 (VF-XMM Aafia) || 7401186 || 1519 || 54741 || || 1415151100
|-
| DLR 50 QR 2503 (eROSITA) || 7401188 || 1519 || 54741 || || 1415151100
|-
| DLR 50 QR 2508 (ATHENA) || 7401191 || 1519 || 54741 || || 1415151100
|-
| DLR 50 OO 2507 (AXIS) || 7401196 || 1519 || 54741 || || 1415151100
|-
| || || || || ||
|-
| DFG WI 1860/17-2 (eRO STEP 1, P5) || 7458208 || 1519 || 54741 || || 1415151100
|-
| DFG WI 1860/19-1 (eRO STEP 1, P6) || 7458046 || 1519 || 54741 || || 1415151100
|-
| DFG WI 1860/20-1 (FOR 5195, P2) || 7458065 || 1519 || 54741 || || 1415151100
|-
| DFG WI 1860/21-1 (eRO STEP 2, P7) || 7458209 || 1518 || 54741 || || 1415151100
|-
| || || || || ||
|-
| DFG overhead WI until 2022 || 5002344 || 1519 || 54740 || PPS || 1415151100
|-
| DFG overhead WI from 2023 || 150234 || 1519 || 54740 || PPS || 1415151100
|-
| || || || || ||
|-
| ESA (DALI) || 7402 745 || 1519 || 54741 || || 1415151100
|-
| Wlms Altprojekte || 7402 304 || 1519 || 54741 || || 1415151100
|-
| ETI Förderung || 5500 245 || 1519 || 54741 || || 1415151100
|-
| || || || || ||
|-
| DFG SA 2131/13-2 (eRO STEP 2, P1) || 7458204 || 1519 || 54741 || || 1415150013
|-
| DFG SA 2131/14-2 (eRO STEP 2, P2) || 7458205 || 1519 || 54741 || || 1415150013
|-
| DFG SA 2131/15-2 (eRO STEP 2, TP Z) || 7458206 || 1519 || 54741 || || 1415150013
|-
| DFG SA 2131/18-1 (eROSITA Galaxien) || 7458168 || 1519 || 54741 || || 1415150013
|-
| || || || || ||
|-
| DFG overhead SA (Altprojekte) || 7459704 || 1519 || 54741 || || 1415150013
|-
| DFG overhead SA bis 2022 || 5002391 || 1519 || 54740 || PPS || 1415150013
|-
| DFG overhead SA ab 2023 || 0150178 || 1519 || 54740 || PPS || 1415150013
|-
| || || || || ||
|-
| DFG SA 4388/2-1 (Saeedi) || 7458207 || 1519 || 54741 || || 1415150013
|-
| DFG MA 11073/1-1 (Mayer) || 7458221 || 1519 || 54741 || || 1415150013
|-
| DFG HE 1356/70-2 (Heber) || 7458225 || 1519 || 54741 || || 1415150000
|-
| || || || || ||
|-
| 73er Titel || 061 000-6 || 1519 || 54740 || FuL || 1415150000
|-
| 72er Titel || 806 3141 || 1519 || 54741 || || 1415150000
|}

Additionally you need to specify the kind of expense (Kostenart): 685000. If the AWK is empty in the table above, do not put anything in the '''Info 1''' field. Otherwise add the given symbol.

== English information ==

Here are some PDFs you might find helpful to navigate through the German landscape of bureaucracy.

Some [[:Media:Additional_information_BayRMS.pdf|additional information]] in Englisch

The [[:Media:Bayrms_eng_data_protection.pdf|data protection waiver]] (you still have to sign the German one!)

The [[:Media:Bayrms_eng_introduction_slides.pdf|introduction slides]]

A [[:Media:Bayrms_glossary.pdf|glossary]] to match English and German terms. (REALLY HELPFUL, CONTAINS INFORMATION TO INSERT)

== ''OUTDATED!'' Business and private travels ==

If you intend to combine a business trip with a vacation to save money or just because of the occasion, you need to observe a couple of issues:

* first of all, combining business and private travel is in principle nothing that the university likes
* you *need* to get the private travel authorized on the travel request form, i.e. you need to state *both* on travel request form
* obviously you will not get any reimbursement for the private part of your trip, or any extra expenses arising from your vacation
* to get reimbursement for your business part of the trip, you need to document what the business part alone would have cost. In detail this means that you need to document:
* fictitious cost of flights/train tickets/rental car/etc for the business part of the trip
* fictitious cost of flights/train tickets/etc to and from the business destination of the trip
* nevertheless you also obviously need to state your actual cost (flight tickets etc).
* the university will reimburse you only the *lesser* of your actual cost and the fictitious cost!\\ This means that if your flight would have cost 1000 Eur, but because you stayed longer for private reasons (i.e. over the weekend) and the actual flight is cheaper like 700 Eur, the university will only reimburse you 700 Eur.

Furthermore apart from the reimbursement by the university, you have also to consider the taxes: the fiscal authorities might consider such a combination of business and private trip entirely private and therefore the reimbursement as additional income. So far,
this has never happened in Bamberg to Jörns knowledge, but in principle tax
regulations state that for a trip to count as a business trip, the
business portion must outbalance the private portion. To give an
example: a 3d observing run in Australia followed by a 2 week vacation
there would probably not be seen as a business related trip (even if it
was!), even though the university would reimburse you for your flights
and the 3d per diem.
((Based on a FAQ Email sent by Jörn to allusers on April 4, 2011))

Travel

2025-05-23T09:47:39Z

Wilms: /* List of project funds */

[[Category:Internal]]

This page documents how to apply for business travel and hand in the reimbursement with the online tool accessible through [https://www.mitarbeiterservice.bayern.de/ authega]. This requires you to have an account set up. If you sign up for the first time you will be send a letter (! yes, physical letter, this can take some days) with information for the login. For further logins it is best to use a certificate file with a password.

Once logged in you can access the travel management (Reisekostenmanagement, RMS) and enter the necessary information there. Certain numbers are tied to the observatory and will always be the same, they are documented below. '''Note:''' When selecting the institution (Beschäftigungsbehöde) do '''not''' use the Remeis-Observatory or any other smaller body. Instead use the general FAU entry with the number '''1519016'''! In the field '''Kapitel''' enter '''1519'''!

More information for the general setup are in the [[:Media:introduction_bayrms.pdf|introductory slides]] (this is the German version, see below for additional guidance in English).

In order to receive documents per email you need to sign the [[:Media:Bayrms_data_protection.pdf|data protection waiver]] (in German!) and hand it in (in paper form!).

== Application for business travel ==

Some notes on filling in these forms:

=== Travel days (Reisetage) ===
On each day, you need to input the start and end of your "business".
If you are, say attending a conference starting Monday at 2 PM and ending on a Friday at noon, your times should look like this:
* Monday: Start at 14:00, end at '''23:59'''
* Tue-Thur: Start at '''0:00''', end at '''23:59'''
* Fri: Start at '''0:00''', end at 12:00

The point here being that you are still there "on business" even outside the main conference hours. Weekends are also part of the trip, if the conference is more than one week long, so this is not "private time" in this form ((c) - Joern)

(NB: There are still discussions between the administration and Joern about this)

=== Meals ===
If food is provided by hotel/conference and you do not pay for it extra - make the corresponding mark in the day

=== Mitzeichner (Signatory, in the very end of the form) ===
This needs to be your boss, who will then forward it to P6.

=== Mitreisende ===
Only employees of Bavaria (e.g., if you drive from work with someone)

=== Hotel costs ===
It is good if you have some proof why you have taken this particular option. Get some documentation (e.g., print web-page with costs) at the moment of booking, which would display other possible options in this hotel or in other hotels around.

If you travel with family, you will not be reimbursed for the difference between the single room and the room you've taken (e.g., double), so you need to document the difference of the room cost AT THE TIME OF BOOKING.

If you are staying somewhere without having to pay, choose "unentgeltliche Uebernachtung".

=== Reimbursement in advance ===
According to Edith, reimbursement in advance requires entering a remark at the end of the form, i.e. we should already have this in mind while filling out the application.

The following may be outdated: If you need to be reimbursed in advance. After approval of the trip, print the trip summary and talk to Edith.)

== Handing in reimbursement ==

== List of project funds ==

Below is a list of project funds that you travel might be payed from. '''Before submitting your reimbursement form ask your supervisor what project to use! Every time!'''

{| class="wikitable" style="margin:auto"
|+ Project numbers
|-
! Name !! Erweiterung !! Kapitel !! Titel !! Info 1 (AWK) !! Kostenstelle
|-
| DLR 50 OR 2309 (VF-ULX) || 7401171 || 1519 || 54741 || || 1415151100
|-
| DLR 50 OO 2417 (THESEUS) || 7401182 || 1519 || 54741 || || 1415151100
|-
| DLR 50 OR 2410 (VF-XMM Aafia) || 7401186 || 1519 || 54741 || || 1415151100
|-
| DLR 50 QR 2503 (eROSITA) || 7401188 || 1519 || 54741 || || 1415151100
|-
| DLR 50 QR 2508 (ATHENA) || 7401191 || 1519 || 54741 || || 1415151100
|-
| DLR 50 OO 2507 (AXIS) || 7401196 || 1519 || 54741 || || 1415151100
|-
| || || || || ||
|-
| DFG WI 1860/17-2 (eRO STEP 1, P5) || 7458208 || 1519 || 54741 || || 1415151100
|-
| DFG WI 1860/19-1 (eRO STEP 1, P6) || 7458046 || 1519 || 54741 || || 1415151100
|-
| DFG WI 1860/20-1 (FOR 5195, P2) || 7458065 || 1519 || 54741 || || 1415151100
|-
| DFG WI 1860/21-1 (eRO STEP 2, P7) || 7458209 || 1518 || 54741 || || 1415151100
|-
| || || || || ||
|-
| DFG overhead WI until 2022 || 5002344 || 1519 || 54740 || PPS || 1415151100
|-
| DFG overhead WI from 2023 || 150234 || 1519 || 54740 || PPS || 1415151100
|-
| || || || || ||
|-
| ESA (DALI) || 7402 745 || 1519 || 54741 || || 1415151100
|-
| Wlms Altprojekte || 7402 304 || 1519 || 54741 || || 1415151100
|-
| ETI Förderung || 5500 245 || 1519 || 54741 || || 1415151100
|-
| || || || || ||
|-
| DFG SA 2131/13-2 (eRO STEP 2, P1) || 7458204 || 1519 || 54741 || || 1415150013
|-
| DFG SA 2131/14-2 (eRO STEP 2, P2) || 7458205 || 1519 || 54741 || || 1415150013
|-
| DFG SA 2131/15-2 (eRO STEP 2, TP Z) || 7458206 || 1519 || 54741 || || 1415150013
|-
| DFG SA 2131/18-1 (eROSITA Galaxien) || 7458168 || 1519 || 54741 || || 1415150013
|-
| || || || || ||
|-
| DFG overhead SA (Altprojekte) || 7459704 || 1519 || 54741 || || 1415150013
|-
| DFG overhead SA bis 2022 || 5002391 || 1519 || 54740 || PPS || 1415150013
|-
| DFG overhead SA ab 2023 || 0150178 || 1519 || 54740 || PPS || 1415150013
|-
| || || || || ||
|-
| DFG SA 4388/2-1 (Saeedi) || 7458207 || 1519 || 54741 || || 1415150013
|-
| DFG MA 11073/1-1 (Mayer) || 7458221 || 1519 || 54741 || || 1415150013
|-
| DFG HE 1356/70-2 (Heber) || 7458225 || 1519 || 54741 || || 1415150000
|-
| || || || || ||
|-
| 73er Titel || 061 000-6 || 1519 || 54740 || FuL || 1415150000
|-
| 72er Titel || 806 3141 || 1519 || 54741 || || 1415150000
|}

Additionally you need to specify the kind of expense (Kostenart): 685000. If the AWK is empty in the table above, do not put anything in the '''Info 1''' field. Otherwise add the given symbol.

== English information ==

Here are some PDFs you might find helpful to navigate through the German landscape of bureaucracy.

Some [[:Media:Additional_information_BayRMS.pdf|additional information]] in Englisch

The [[:Media:Bayrms_eng_data_protection.pdf|data protection waiver]] (you still have to sign the German one!)

The [[:Media:Bayrms_eng_introduction_slides.pdf|introduction slides]]

A [[:Media:Bayrms_glossary.pdf|glossary]] to match English and German terms. (REALLY HELPFUL, CONTAINS INFORMATION TO INSERT)

== ''OUTDATED!'' Business and private travels ==

If you intend to combine a business trip with a vacation to save money or just because of the occasion, you need to observe a couple of issues:

* first of all, combining business and private travel is in principle nothing that the university likes
* you *need* to get the private travel authorized on the travel request form, i.e. you need to state *both* on travel request form
* obviously you will not get any reimbursement for the private part of your trip, or any extra expenses arising from your vacation
* to get reimbursement for your business part of the trip, you need to document what the business part alone would have cost. In detail this means that you need to document:
* fictitious cost of flights/train tickets/rental car/etc for the business part of the trip
* fictitious cost of flights/train tickets/etc to and from the business destination of the trip
* nevertheless you also obviously need to state your actual cost (flight tickets etc).
* the university will reimburse you only the *lesser* of your actual cost and the fictitious cost!\\ This means that if your flight would have cost 1000 Eur, but because you stayed longer for private reasons (i.e. over the weekend) and the actual flight is cheaper like 700 Eur, the university will only reimburse you 700 Eur.

Furthermore apart from the reimbursement by the university, you have also to consider the taxes: the fiscal authorities might consider such a combination of business and private trip entirely private and therefore the reimbursement as additional income. So far,
this has never happened in Bamberg to Jörns knowledge, but in principle tax
regulations state that for a trip to count as a business trip, the
business portion must outbalance the private portion. To give an
example: a 3d observing run in Australia followed by a 2 week vacation
there would probably not be seen as a business related trip (even if it
was!), even though the university would reimburse you for your flights
and the 3d per diem.
((Based on a FAQ Email sent by Jörn to allusers on April 4, 2011))

Travel

2025-05-16T09:19:37Z

Wilms: /* Hotel costs */

[[Category:Internal]]

This page documents how to apply for business travel and hand in the reimbursement with the online tool accessible through [https://www.mitarbeiterservice.bayern.de/ authega]. This requires you to have an account set up. If you sign up for the first time you will be send a letter (! yes, physical letter, this can take some days) with information for the login. For further logins it is best to use a certificate file with a password.

Once logged in you can access the travel management (Reisekostenmanagement, RMS) and enter the necessary information there. Certain numbers are tied to the observatory and will always be the same, they are documented below. '''Note:''' When selecting the institution (Beschäftigungsbehöde) do '''not''' use the Remeis-Observatory or any other smaller body. Instead use the general FAU entry with the number '''1519016'''! In the field '''Kapitel''' enter '''1519'''!

More information for the general setup are in the [[:Media:introduction_bayrms.pdf|introductory slides]] (this is the German version, see below for additional guidance in English).

In order to receive documents per email you need to sign the [[:Media:Bayrms_data_protection.pdf|data protection waiver]] (in German!) and hand it in (in paper form!).

== Application for business travel ==

Some notes on filling in these forms:

=== Travel days (Reisetage) ===
On each day, you need to input the start and end of your "business".
If you are, say attending a conference starting Monday at 2 PM and ending on a Friday at noon, your times should look like this:
* Monday: Start at 14:00, end at '''23:59'''
* Tue-Thur: Start at '''0:00''', end at '''23:59'''
* Fri: Start at '''0:00''', end at 12:00

The point here being that you are still there "on business" even outside the main conference hours. Weekends are also part of the trip, if the conference is more than one week long, so this is not "private time" in this form ((c) - Joern)

(NB: There are still discussions between the administration and Joern about this)

=== Meals ===
If food is provided by hotel/conference and you do not pay for it extra - make the corresponding mark in the day

=== Mitzeichner (Signatory, in the very end of the form) ===
This needs to be your boss, who will then forward it to P6.

=== Mitreisende ===
Only employees of Bavaria (e.g., if you drive from work with someone)

=== Hotel costs ===
It is good if you have some proof why you have taken this particular option. Get some documentation (e.g., print web-page with costs) at the moment of booking, which would display other possible options in this hotel or in other hotels around.

If you travel with family, you will not be reimbursed for the difference between the single room and the room you've taken (e.g., double), so you need to document the difference of the room cost AT THE TIME OF BOOKING.

If you are staying somewhere without having to pay, choose "unentgeltliche Uebernachtung".

=== Reimbursement in advance ===
According to Edith, reimbursement in advance requires entering a remark at the end of the form, i.e. we should already have this in mind while filling out the application.

The following may be outdated: If you need to be reimbursed in advance. After approval of the trip, print the trip summary and talk to Edith.)

== Handing in reimbursement ==

== List of project funds ==

Below is a list of project funds that you travel might be payed from. '''Before submitting your reimbursement form ask your supervisor what project to use! Every time!'''

{| class="wikitable" style="margin:auto"
|+ Project numbers
|-
! Name !! Erweiterung !! Titel !! AWK !! Kostenstelle
|-
| DLR 50 OR 2309 (VF-ULX) || 7401 171 || 547 41 || || 1415151100
|-
| DLR 50 OO 2417 (THESEUS) || 7401 182 || 547 41 || || 1415151100
|-
| DLR 50 OR 2410 (VF-XMM Aafia) || 7401 186 || 547 41 || || 1415151100
|-
| DLR 50 QR 2503 (eROSITA) || 7401 188 || 547 41 || || 1415151100
|-
| DLR 50 QR 2508 (ATHENA) || 7401 191 || 547 41 || || 1415151100
|-
| DLR 50 OO 2507 (AXIS) || 7401 196 || 547 41 || || 1415151100
|-
| || || || ||
|-
| DFG WI 1860/17-2 (eRO STEP 1, P5) || 7458 208 || 547 41 || || 1415151100
|-
| DFG WI 1860/19-1 (eRO STEP 1, P6) || 7458 046 || 547 41 || || 1415151100
|-
| DFG WI 1860/20-1 (FOR 5195, P2) || 7458 065 || 547 41 || || 1415151100
|-
| DFG WI 1860/21-1 (eRO STEP 2, P7) || 7458 209 || 547 41 || || 1415151100
|-
| || || || ||
|-
| DFG overhead WI bis 2022 || 5002344 || 547 40 || PPS || 1415151100
|-
| DFG overhead WI ab 2023 || 150234 || 547 40 || PPS || 1415151100
|-
| || || || ||
|-
| ESA (DALI) || 7402 745 || 547 41 || || 1415151100
|-
| Wlms Altprojekte || 7402 304 || 547 41 || || 1415151100
|-
| ETI Förderung || 5500 245 || 547 41 || || 1415151100
|-
| || || || ||
|-
| DFG SA 2131/13-2 (eRO STEP 2, P1) || 7458 204 || 547 41 || || 1415150013
|-
| DFG SA 2131/14-2 (eRO STEP 2, P2) || 7458 205 || 547 41 || || 1415150013
|-
| DFG SA 2131/15-2 (eRO STEP 2, TP Z) || 7458 206 || 547 41 || || 1415150013
|-
| DFG SA 2131/18-1 (eROSITA Galaxien) || 7458 168 || 547 41 || || 1415150013
|-
| || || || ||
|-
| DFG overhead SA (Altprojekte) || 7459 704 || 547 41 || || 1415150013
|-
| DFG overhead SA bis 2022 || 5002391 || 547 40 || PPS || 1415150013
|-
| DFG overhead SA ab 2023 || 0150178 || 547 40 || PPS || 1415150013
|-
| || || || ||
|-
| DFG SA 4388/2-1 (Saeedi) || 7458 207 || 547 41 || || 1415150013
|-
| DFG MA 11073/1-1 (Mayer) || 7458 221 || 547 41 || || 1415150013
|-
| DFG HE 1356/70-2 (Heber) || 7458 225 || 547 41 || || 1415150000
|-
| || || || ||
|-
| 73er Titel || 061 000-6 || 547 40 || FuL || 1415150000
|-
| 72er Titel || 806 3141 || 547 41 || || 1415150000
|}

Additionally you need to specify the kind of expense (Kostenart): 685000. If the AWK is empty in the table above, do not put anything in the '''Info 1''' field. Otherwise add the given symbol.

== English information ==

Here are some PDFs you might find helpful to navigate through the German landscape of bureaucracy.

Some [[:Media:Additional_information_BayRMS.pdf|additional information]] in Englisch

The [[:Media:Bayrms_eng_data_protection.pdf|data protection waiver]] (you still have to sign the German one!)

The [[:Media:Bayrms_eng_introduction_slides.pdf|introduction slides]]

A [[:Media:Bayrms_glossary.pdf|glossary]] to match English and German terms. (REALLY HELPFUL, CONTAINS INFORMATION TO INSERT)

== ''OUTDATED!'' Business and private travels ==

If you intend to combine a business trip with a vacation to save money or just because of the occasion, you need to observe a couple of issues:

* first of all, combining business and private travel is in principle nothing that the university likes
* you *need* to get the private travel authorized on the travel request form, i.e. you need to state *both* on travel request form
* obviously you will not get any reimbursement for the private part of your trip, or any extra expenses arising from your vacation
* to get reimbursement for your business part of the trip, you need to document what the business part alone would have cost. In detail this means that you need to document:
* fictitious cost of flights/train tickets/rental car/etc for the business part of the trip
* fictitious cost of flights/train tickets/etc to and from the business destination of the trip
* nevertheless you also obviously need to state your actual cost (flight tickets etc).
* the university will reimburse you only the *lesser* of your actual cost and the fictitious cost!\\ This means that if your flight would have cost 1000 Eur, but because you stayed longer for private reasons (i.e. over the weekend) and the actual flight is cheaper like 700 Eur, the university will only reimburse you 700 Eur.

Furthermore apart from the reimbursement by the university, you have also to consider the taxes: the fiscal authorities might consider such a combination of business and private trip entirely private and therefore the reimbursement as additional income. So far,
this has never happened in Bamberg to Jörns knowledge, but in principle tax
regulations state that for a trip to count as a business trip, the
business portion must outbalance the private portion. To give an
example: a 3d observing run in Australia followed by a 2 week vacation
there would probably not be seen as a business related trip (even if it
was!), even though the university would reimburse you for your flights
and the 3d per diem.
((Based on a FAQ Email sent by Jörn to allusers on April 4, 2011))

Remeis English Checklist

2025-05-08T10:08:57Z

Wilms: /* The Remeis English Checklist */

====== The Remeis English Checklist ======

(by J. Wilms and K. Pottschmidt)

'''''First of all and most importantly:'''''

* did you read the instructions to authors of the journal? If you are working on a thesis, did you read those of Astronomy and Astrophysics on [https://www.aanda.org/for-authors/language-editing/1-introduction language] and the TeX instructions in file aadoc.pdf, which is part of the Astronomy and Astrophysics package?
* did you read appendix A of the [https://journals.aps.org/files/rmpguide.pdf instructions to authors] of Rev Mod Phys?

==== Punctuation ====

* did you remove all commas before "that"?
* did you end your footnotes and captions with a full stop (".")?
* did you make sure that your use of "data" is correct and uses plural verbs?
* did you make sure that you do not have a ":" anywhere before an equation, but that your equations are seen as part of your sentences?
* did you make sure that you have commas surrounding "i.e." and "e.g."?

==== Spelling and Word usage ====

* do you consistently use either British or American spelling?
* did you run a spell checker over your manuscript? For TeX, use "ispell" or the built in spell checker in emacs.
* did you make sure not to use country prefixes in addresses in the author list?
* did you avoid passive voice as much as possible?
* did you make sure that you are //not// using "The found results are..." and similar German constructs in your text?
* did you make sure that everything in your text that is not your original result is accompanied by proper citations?
* did you make sure that you distinguish between "estimate" and "estimation" by replacing all "estimation" with "estimate"?
* did you replace all uses of "exemplary" by "example"?
* did you use "short" for length intervals and "brief" for time intervals? (but note that "short of duration" is correct)
* did you replace all uses of "the actual value" by "the real value"? (if you are German, "actual" does not mean "aktuell"!)
* did you remove all uses of "hence" and "thereby"?
* did you make sure that you use "however" as sparingly as possible?
* did you make sure that you did not use "the equation reads..", but rather used "the equation is..." or "the equation is given by..."?
* did you avoid split infinitives? ("to boldly go..." is wrong; yes, in many cases split infinitives are ok in current English, but they tend to be so often used wrongly by non-native speakers that it is best to avoid them)
* did you make sure that you distinguish properly between "this" and "these"?
* did you make use of the "Oxford comma", i.e., do you have a comma before "and" in lists?
* did you use "i.e." and "e.g." correctly, i.e., using "i.e." for a specific clarification or definition and "e.g." where you would otherwise use "for example"?
* did you use the IAU recommended year - month - day sequences (2016 March 15)?
* did you make sure that you did not use contractions such as "didn't" or "you're"?
* did you replace "cf." with "see" everywhere since you know that "cf." means "compare"?
* did you ensure that you use "opportunity" where in German you would be using "Chance" or "Gelegenheit" (and did not use "chance"...)?
* did you make sure that the reader will understand what thing you refer to when using "it" rather than naming it?
* did you make sure that all uses of "this" are followed by the object you are referring to?
* did you use "led" rather than "lead" when using the past tense of the verb "to lead"?
* did you reread the manuscript for internal consistency after you added comments from your coauthors?
* did you make sure that your sentences are short (rule of thumb: if a sentence goes over more than three lines it is probably too long)?
* did you check that you did not combine two sentences that could be separate sentences with "and"?
* did you avoid abbreviations as much as possible and only used them when they are really, really common (HST, AGN, XMM,...)?
* did you check that you defined all abbreviations that you used at their first usage? ("...Active Galactic Nucleus (AGN)..." //not// "...AGN (Active Galactic Nucleus)..." )

==== Citations ====

* did you add the journal to all publications where you list the arXiv-reference and not just blindly copy the erroneous ADS bibtex entry?
* did you make sure that you distinguished between arXiv references where a paper is submitted and references where a paper is already accepted by checking the paper author's comment on the arXiv-page for that article?
* did you remove the page number for all ATEL-references downloaded from ADS and changed the journal name to "Astron. Tel." or "ATEL"? (and similar for IAU telegrams)
* did you add editors and the title of the conference publication to all conference publications?
* did you add the publisher and place information (city only) to all books, conference publications, and other book-like publications that you are citing?
* did you check that your references are correct in that you are using ''\citet{biblabel}'' for references in the text and ''\citep{biblabel}'' for references in parentheses?
* did you make sure that none of your ''\citet{..}'' commands refer to more than one biblabel?
* [added by O. Koenig: did you make sure all SPIE references have an address? (you may want to follow this procedure: go to NASA ADS to get bibtex entry (<code>@inproceedings</code>!), put the entry of "booktitle" into "series", put <code>booktitle = procspie</code> (there should be a <code>@STRING{procspie = "Proc. SPIE."}</code> in <code>mnemonic.bib</code>, go to the SPIE webpage of the paper, get the address, and insert it by hand. A MWE could be <code>@INPROCEEDINGS{Doehring2015a, author = {{D{\"o}hring}, T. and {...}, title = "{The challenge of developing thin mirror shells for future x-ray telescopes}", series = {Optical Systems Design 2015: Optical Fabrication, Testing, and Metrology V}, year = 2015, editor = {{Duparr}, A. and {Geyl}, R.}, booktitle = procspie, volume = {9628}, address = {Jena, Germany}, pages = {962809}}</code>)]

==== Typesetting (mainly in TeX) ====

* did you check for missing spaces between values and units?
* did you make sure that all scientific units are typeset in <code>\mathrm</code>?
* did you make sure not to use constructs such as <code>$\mathrm{m}/\mathrm{s}$</code> by using <code>$\mathrm{m}\,\mathrm{s}^{-1}$</code> instead?
* did you make sure that almost all of your error bars are rounded up to only one significant digit rather than following the DIN-norm (which is not applied in astronomical journals)?
* did you make sure that you are not using any positioning commands for the table or figure environment such as <code>\begin{table}[htpb]</code>?
* did you make sure that your tables have captions above the table, and figures have captions below the figure or next to it (where allowed by the style)?
* did you make sure that you use empty lines to denote the start of a new paragraph rather than the ''\\''-command? (use <code>\parindent{0pt}</code> if you do not want to indent paragraphs)
* did you make sure that there are no paragraph endings above or below <code>\begin{equation}...\end{equation}</code> by ensuring that there is no empty line above or below the ''equation''-environment?
* did you make sure that you are not using <code>$\frac{a}{b}$</code> in normal text, but use <code>$a/b$</code> instead?
* did you make sure that you are not using the <code>displaymath</code>-environment and that all equations are numbered?
* did you make sure that all of your sections, subsections, paragraphs and so on are numbered?
* did you avoid any and all uses of <code>\bf</code>, <code>\it</code>, <code>\sl</code>, or <code>\em</code> and use the proper commands <code>\textbf</code>, <code>\textit</code>, <code>\textsl</code>, and <code>\emph</code> instead?
* did you use the en-dash of TeX for ranges, even if they occur in math, by using <code>--</code> in text mode rather than a minus sign? (that is, did you typeset a range in an equation as <code>$3x$--$5x$</code> or <code>$3x\mbox{--}5x$</code> rather than, erroneously, <code>$3x-5x$</code>?
* did you correctly use the minus-sign and dashes in astronomical source names, where the name contains coordinates and the <q>dash</q> really is a southern declination or Galactic latitude, that is, did you typeset <code>Her X-1</code>, <code>LMC X-3</code>, but <code>GX\,339$-$4</code> or <code>IGR J16318$-$4848</code> (and as a really difficult one: <code>MCG$-$6-30-15</code>)?
** as a side note: When the first part of the source name is a constellation name (e.g., Her X-1) it should be followed by a full space (<code>~</code>), while if the first part of the source name is a catalog (GX, 4U, 2RXS), it should be followed by a half-space (<code>\,</code>).
* did you make sure to typeset hydrogen equivalent columns as <code>$N_\mathrm{H}$</code> rather than $n_H$ or $n_\mathrm{H}$? (note: in astronomy, $n$ denotes a particle density, so it has units of particles per cubic centimeter, while N is a column with units of particles per square centimeter; a certain analysis program uses nH for this parameter, but this does not mean that n should be used in papers).

[[Category:Current Members]]

Travel

2025-05-07T08:14:41Z

Wilms: /* Travel days (Reisetage) */

[[Category:Internal]]

This page documents how to apply for business travel and hand in the reimbursement with the online tool accessible through [https://www.mitarbeiterservice.bayern.de/ authega]. This requires you to have an account set up. If you sign up for the first time you will be send a letter (! yes, physical letter, this can take some days) with information for the login. For further logins it is best to use a certificate file with a password.

Once logged in you can access the travel management (Reisekostenmanagement, RMS) and enter the necessary information there. Certain numbers are tied to the observatory and will always be the same, they are documented below. '''Note:''' When selecting the institution (Beschäftigungsbehöde) do '''not''' use the Remeis-Observatory or any other smaller body. Instead use the general FAU entry with the number '''1519016'''! In the field '''Kapitel''' enter '''1519'''!

More information for the general setup are in the [[:Media:introduction_bayrms.pdf|introductory slides]] (unfortunately only in German, but mostly with images so you should at least get the right buttons from it).

== Application for business travel ==

Some notes on filling in these forms:

=== Travel days (Reisetage) ===
On each day, you need to input the start and end of your "business".
If you are, say attending a conference starting Monday at 2 PM and ending on a Friday at noon, your times should look like this:
* Monday: Start at 14:00, end at '''23:59'''
* Tue-Thur: Start at '''0:00''', end at '''23:59'''
* Fri: Start at '''0:00''', end at 12:00

The point here being that you are still there "on business" even outside the main conference hours.

(NB: There are still discussions between the administration and Joern about this)

=== Mitzeichner (Signatory) ===
This needs to be your boss, who will then forward it to P6.

== Handing in reimbursement ==

== List of project funds ==

Below is a list of project funds that you travel might be payed from. '''Before submitting your reimbursement form ask your supervisor what project to use! Every time!'''

{| class="wikitable" style="margin:auto"
|+ Project numbers
|-
! Name !! Erweiterung !! Titel !! AWK !! Kostenstelle
|-
| DLR 50 OR 2309 (VF-ULX) || 7401 171 || 547 41 || || 1415151100
|-
| DLR 50 OO 2417 (THESEUS) || 7401 182 || 547 41 || || 1415151100
|-
| DLR 50 OR 2410 (VF-XMM Aafia) || 7401 186 || 547 41 || || 1415151100
|-
| DLR 50 QR 2503 (eROSITA) || 7401 188 || 547 41 || || 1415151100
|-
| DLR 50 QR 2508 (ATHENA) || 7401 191 || 547 41 || || 1415151100
|-
| DLR 50 OO 2507 (AXIS) || 7401 196 || 547 41 || || 1415151100
|-
| || || || ||
|-
| DFG WI 1860/17-2 (eRO STEP 1, P5) || 7458 208 || 547 41 || || 1415151100
|-
| DFG WI 1860/19-1 (eRO STEP 1, P6) || 7458 046 || 547 41 || || 1415151100
|-
| DFG WI 1860/20-1 (FOR 5195, P2) || 7458 065 || 547 41 || || 1415151100
|-
| DFG WI 1860/21-1 (eRO STEP 2, P7) || 7458 209 || 547 41 || || 1415151100
|-
| || || || ||
|-
| DFG overhead WI bis 2022 || 5002344 || 547 40 || PPS || 1415151100
|-
| DFG overhead WI ab 2023 || 150234 || 547 40 || PPS || 1415151100
|-
| || || || ||
|-
| ESA (DALI) || 7402 745 || 547 41 || || 1415151100
|-
| Wlms Altprojekte || 7402 304 || 547 41 || || 1415151100
|-
| ETI Förderung || 5500 245 || 547 41 || || 1415151100
|-
| || || || ||
|-
| DFG SA 2131/13-2 (eRO STEP 2, P1) || 7458 204 || 547 41 || || 1415150013
|-
| DFG SA 2131/14-2 (eRO STEP 2, P2) || 7458 205 || 547 41 || || 1415150013
|-
| DFG SA 2131/15-2 (eRO STEP 2, TP Z) || 7458 206 || 547 41 || || 1415150013
|-
| DFG SA 2131/18-1 (eROSITA Galaxien) || 7458 168 || 547 41 || || 1415150013
|-
| || || || ||
|-
| DFG overhead SA (Altprojekte) || 7459 704 || 547 41 || || 1415150013
|-
| DFG overhead SA bis 2022 || 5002391 || 547 40 || PPS || 1415150013
|-
| DFG overhead SA ab 2023 || 0150178 || 547 40 || PPS || 1415150013
|-
| || || || ||
|-
| DFG SA 4388/2-1 (Saeedi) || 7458 207 || 547 41 || || 1415150013
|-
| DFG MA 11073/1-1 (Mayer) || 7458 221 || 547 41 || || 1415150013
|-
| DFG HE 1356/70-2 (Heber) || 7458 225 || 547 41 || || 1415150000
|-
| || || || ||
|-
| 73er Titel || 061 000-6 || 547 40 || FuL || 1415150000
|-
| 72er Titel || 806 3141 || 547 41 || || 1415150000
|}

Additionally you need to specify the kind of expense (Kostenart): 685000. If the AWK is empty in the table above, do not put anything in the '''Info 1''' field. Otherwise add the given symbol.

== ''OUTDATED!'' Business and private travels ==

If you intend to combine a business trip with a vacation to save money or just because of the occasion, you need to observe a couple of issues:

* first of all, combining business and private travel is in principle nothing that the university likes
* you *need* to get the private travel authorized on the travel request form, i.e. you need to state *both* on travel request form
* obviously you will not get any reimbursement for the private part of your trip, or any extra expenses arising from your vacation
* to get reimbursement for your business part of the trip, you need to document what the business part alone would have cost. In detail this means that you need to document:
* fictitious cost of flights/train tickets/rental car/etc for the business part of the trip
* fictitious cost of flights/train tickets/etc to and from the business destination of the trip
* nevertheless you also obviously need to state your actual cost (flight tickets etc).
* the university will reimburse you only the *lesser* of your actual cost and the fictitious cost!\\ This means that if your flight would have cost 1000 Eur, but because you stayed longer for private reasons (i.e. over the weekend) and the actual flight is cheaper like 700 Eur, the university will only reimburse you 700 Eur.

Furthermore apart from the reimbursement by the university, you have also to consider the taxes: the fiscal authorities might consider such a combination of business and private trip entirely private and therefore the reimbursement as additional income. So far,
this has never happened in Bamberg to Jörns knowledge, but in principle tax
regulations state that for a trip to count as a business trip, the
business portion must outbalance the private portion. To give an
example: a 3d observing run in Australia followed by a 2 week vacation
there would probably not be seen as a business related trip (even if it
was!), even though the university would reimburse you for your flights
and the 3d per diem.
((Based on a FAQ Email sent by Jörn to allusers on April 4, 2011))

Xmm

2024-01-04T15:30:39Z

Wilms: /* Workaround for the xmmscripts */

== Data ==

Always use the remeis archives at /eu/X-ray/XMM/data/ instead of downloading observation files yourself. You can search for the data of an observation by typing something like '''find /eu/X-ray/xmm/data/????/obsID/odf -type d''' - replacing obsID with your observation ID.
If the observation you want to analyze is not in the archives: contact the XMM admin (Jonathan Knies) and the observation will be downloaded for you.

== XMM EPIC Data Extraction ==

After the system was updated from Ubuntu 11 to Ubuntu 12 a problem occured with the function "dssetattr" inside the "epchain".
This function can set/add an attribute to the HDU (Header/Data Unit).
The solution is to call
''''source $SOFTDIR/sas_init.csh''''
at the beginning of each script in order to initialize SAS inside your script.

A little example script:

#!/bin/csh
source $SOFTDIR/sas_init.csh # initialize the SAS software
set xmmscripts = ${XMMTOOLS} # make sure the proper xmmscripts are loaded

set obsid = '0147190101'
set datadir = /eu/X-ray/XMM/data/????/$obsid/odf

${xmmscripts}/xmmprepare --datadir=$datadir --prepdir=$obsid --pn # prepare the data
${xmmscripts}/xmmextract --prepdir=$obsid --pn --full # full extraction of the chip
${xmmscripts}/xmmextract --prepdir=$obsid --pn --srcreg=src.fits --bkgreg=bkg.fits # source and background extraction of the chip

Note that it is usually better to have the data preparation and the extraction in separate scripts (since one usually prepares once and then tries several extractions with different settings).

The xmmscripts need the region files to be fits files. You can convert them via
ds9tocxc outset=outfilename.fits < infilename.reg

For simple extractions of point sources creating region files is not necessary, you can just give the position of the source and background region as well as their extraction radii with the "--ra", "--dec" and "--bkgra", "--bkgdec" arguments.

"xmmextract" is a very powerful script, use its "--help" argument to get a list of all arguments.

Further important points:

# If your observation includes sub-observations, choose one of them. Do this with "onlyexp=1" not "onlyexp=PNU001" for example.
# Since our Calibration database gets updated frequently, we ran into the problem that new calibration files only like the latest SAS. As it is very problematic to just install the new SAS, there is a workaround. You have to address the calibration files that are working with our SAS version until the new SAS is installed (we must be patient as this is not trivial). The following, however, works perfectly:

example:

#!/bin/csh
${XMMTOOLS}/xmmprepare --datadir=/eu/X-ray/XMM/data/2290/0679780201/odf/
--prepdir=./test --pn --analysisdate=2014-01-11T01:05:00.000

== XMM OM Data Extraction ==

For extracting the data of the Optical Monitor (OM) onboard XMM, there exist three tools which do this automatically: ''omichain'', ''omfchain'' and ''omgchain''.
"i" stands for image mode, "f" for fast mode and "g" for grism mode. Which mode you have can be found on the XMM log browse site: http://xmm2.esac.esa.int/external/xmm_obs_info/obs_view_frame.shtml.
If you want to extract your images you first have to set some paths:

$source $SOFTDIR/sas_init.csh
$setenv SAS_ODF path_to_your_data #normally /eu/X-ray/XMM/data/rev/ObsID/odf/
$cifbuild
$setenv SAS_CCF ccf.cif
$odfingest
$setenv SAS_ODF `ls -1 *SUM.SAS`

After this you can run

$omichain #or omfchain, omgchain

You can also do the extraction step-by-step. For a description see http://xmm.esac.esa.int/sas/current/documentation/threads/omi_stepbystep.shtml.
At the end you should have several images (<code>*IMAGE*</code>), region files (<code>*REGION*</code>) and source lists (<code>*SWSRLI*</code>) for the OM exposures and filters. The nomenclatur for the files are:

* IOOOOOOOOOODDUEEETTTTTTSXXX.FFF or POOOOOOOOOODDUEEETTTTTTSXXX.FFF (for PPS product files)
* OOOOOOOOOO = XMM-ObsID (10 characters)
* DD = Data source idetifier (here OM)
* U = exposure flag (S = sched, U = unsched, X = not aplicable)
* EEE = exposure number within the instrument observation (3 characters)
* TTTTTT = product type (6 characters)
* S = 0 or data subset number/character
* XXX = source number or slew step number (3 characters)
* FFF = file format (3 characters)

From all exposures for one filter a mosaiced sky image is produced which contains *SIMAG?.FIT. The ? stands for the filter: L = UVW1, M = UVM2, S = UVW2, B = B, U = U, V = V.
Open the image with ds9 and have a look if your source is seen and where it is. You can check this by loading a region file, produced e.g. by simbad2ds9, into the image.

Then check the detector images (<code>P*IMAGE_*000.FIT</code>) for your source (it can be, that some detector images don't contain your source because the window was off). Load the region file which belongs to the detector image (<code>*REGION*000.ASC</code>, e.g. <code>P0090050801OMS006IMAGE_0000.FIT</code> -> ''I0090050801OMS006REGION0000.ASC</code>) and identify the number of your source.

[[File:image_region.jpeg|thumb]]

Look into the source list for your exposure (<code>P*SWSRLI*.FIT</code>) and note the SRC_ID in the last column. Open the combined source list (<code>*COMBO*</code>) and search for your SRC_ID. Here you can find all the magnitudes and fluxes of your source for the different filters.

== Choosing correct XMM-EPIC filter ==

Choosing the correct EPIC filter for your observation depends on the
visual magnitudes of the other objects (usually stars) in the EPIC
field of view.

The XMM user's handbook (sect. 3.3.6;
http://xmm.esac.esa.int/external/xmm_user_support/documentation/uhb/epicfilters.html) recommends:

Thick filter: suppress up to magnitudes of -2 to -1 (pn), or +1 to +4 (mos)

Medium filter: if there is nothing above magnitude ~ 6 to 9

Thin filter: for point sources that are 12 mag fainter than thick filter limitations

The UHB notes that these magnitudes apply when you use the full frame mode; if you use a partial window mode, then sources up to 2-3 magnitudes brighter than these values should be okay.

Use the United States Naval Observatory catalog at
http://www.nofs.navy.mil/data/fchpix/ to find the stars within a 9'
radius.

At that website, enter your R.A. and Decl., and for the output file
options in the left column, unclick everything except RA,DEC,
magnitude, and offset from center. Then click 'retrieve data' in the
right column.

Next window: Click on "USNO B1.0 Star List" to download a gzipped
ASCII file with typically hundreds of rows/stars for lines of sight
away from the Galactic Plane (or many thousands of rows/stars for
lines of sight in the Galactic Plane).

Example file: See /home/markowitz/proposals/xmm2014/GS1826USNO for a
Galactic XRB, GS1826, located in the Galactic Bulge (optically-crowded
fields).

The star list is ordered by R.A., and but you can then re-order the ASCII list
by magnitude, e.g.,

cat GS1826USNO | grep -v '#' | awk '{print $7 " " $12}' | sort -g > starlist_sortB
cat GS1826USNO | grep -v '#' | awk '{print $8 " " $12}' | sort -g > starlist_sortR

since the B and R magnitudes are columns 7 and 8, and distance from the center
of f.o.v. (in arcsec) is column 12

Ignore the rows with zero magnitudes; a zero means unmeasured flux.

For these example files, e.g., /home/markowitz/proposals/xmm2014/starlist_sortB
we see that the brightest B- and R-band magnitudes are 10.0-10.3, including some
objects that are only 3-5' from the center, and at least one that's only 1.2'
from the center, so one cannot use the thin epic filter; one must use
the MEDIUM filter for all three EPIC cameras.

== XMM ESAS ==

If you are interested in diffuse X-ray emission it is recommended to use the XMM-Newton Extended Source Analysis Software.
The manual can be found at [https://heasarc.gsfc.nasa.gov/docs/xmm/esas/cookbook/xmm-esas.html] with very detailed step-by-step instructions.

==== Working with XMM ESAS in the remeis environment ====

Before you start with the data analysis you have to source the SAS init via '''source $SOFTDIR/sas_init.csh'''.
Since you will need this every time you start a new terminal it is recommended to add an alias to your .cshrc in your home directory, e.g. '''alias setsas 'source $SOFTDIR/sas_init.csh''''.

First you have to find out the observation data path in the archives, which can be done by typing '''find /eu/X-ray/xmm/data/????/obsID/odf -type d''', where you replace obsID with your desired observation.
Next, you have to set up the environment variables for the SAS tasks to function properly.

Create an analysis directory somewhere in your userdata (usually one analyzed observation has > 1 GB so don't use your home).
Set the following environment variables:

setenv SAS_ODF DIR - where DIR is the observation data path from above.
setenv SAS_CCF ANALYSIS_DIR/ccf.cif - where ANALYSIS_DIR is your directory for the analysis (on userdata), you have to add '/ccf.cif' to this path. This will create the ccf.cif file in your directory when running cifbuild
setenv CALDB_ESAS /userdata/data/knies/XMM/CALDB_ESAS (*)
* You need additional calibration files for ESAS. The latest version can be found at /userdata/data/knies/XMM/CALDB_ESAS. Please use this directory instead of downloading it again to safe disk space.

Next you have to run the basic tasks to prepare the data, but with some different options since we are working in the remeis environment:

cifbuild withccfpath=no analysisdate=now category=XMMCCF calindexset=$SAS_CCF fullpath=yes
odfingest outdir=ANALYSIS_DIR

''Important'': you can't move your files after running these steps or you will get errors.

After odfingest is finished there should be a file ending with "SUM.SAS" in your directory. Note the filename and re-set the SAS_ODF variable:

setenv SAS_ODF ANALYSIS_DIR/*SUM.SAS - replace *SUM.SAS with the filename in your directory

After this step you can follow the ESAS manual normally, starting with [https://heasarc.gsfc.nasa.gov/docs/xmm/esas/cookbook/xmm-esas.html#SECTION00082000000000000000].
Note that you have to do cifbuild and odfingest only once (and also when SAS was updated) but you have to set the environment variables each time you open a new terminal.
You can make a small shell script which you can execute each time before you continue your analysis to speed this up, e.g.:

#!/bin/tcsh -f
source $SOFTDIR/sas_init.csh
setenv SAS_ODF ANALYSIS_DIR/*SUM.SAS
setenv SAS_CCF ANALYSIS_DIR/ccf.cif
setenv CALDB_ESAS /userdata/data/knies/XMM/CALDB_ESAS

Replace the directories etc. like shown above, make your script executable with chmod +x scriptfile and then execute it with ./scriptfile.

[[Category:Data Extraction]]

Xmm

2024-01-04T15:28:49Z

Wilms: /* XMM EPIC Data Extraction */

== Data ==

Always use the remeis archives at /eu/X-ray/XMM/data/ instead of downloading observation files yourself. You can search for the data of an observation by typing something like '''find /eu/X-ray/xmm/data/????/obsID/odf -type d''' - replacing obsID with your observation ID.
If the observation you want to analyze is not in the archives: contact the XMM admin (Jonathan Knies) and the observation will be downloaded for you.

== XMM EPIC Data Extraction ==

After the system was updated from Ubuntu 11 to Ubuntu 12 a problem occured with the function "dssetattr" inside the "epchain".
This function can set/add an attribute to the HDU (Header/Data Unit).
The solution is to call
''''source $SOFTDIR/sas_init.csh''''
at the beginning of each script in order to initialize SAS inside your script.

A little example script:

#!/bin/csh
source $SOFTDIR/sas_init.csh # initialize the SAS software
set xmmscripts = ${XMMTOOLS} # make sure the proper xmmscripts are loaded

set obsid = '0147190101'
set datadir = /eu/X-ray/XMM/data/????/$obsid/odf

${xmmscripts}/xmmprepare --datadir=$datadir --prepdir=$obsid --pn # prepare the data
${xmmscripts}/xmmextract --prepdir=$obsid --pn --full # full extraction of the chip
${xmmscripts}/xmmextract --prepdir=$obsid --pn --srcreg=src.fits --bkgreg=bkg.fits # source and background extraction of the chip

Note that it is usually better to have the data preparation and the extraction in separate scripts (since one usually prepares once and then tries several extractions with different settings).

The xmmscripts need the region files to be fits files. You can convert them via
ds9tocxc outset=outfilename.fits < infilename.reg

For simple extractions of point sources creating region files is not necessary, you can just give the position of the source and background region as well as their extraction radii with the "--ra", "--dec" and "--bkgra", "--bkgdec" arguments.

"xmmextract" is a very powerful script, use its "--help" argument to get a list of all arguments.

==== Workaround for the xmmscripts ====
There were some problems occuring with the XMM-data extraction. Joern has implemented a workaround in the xmmscripts that has to be called as shown in the example below.
Here the issues:
# If your observation includes sub-observations, choose one of them. Do this with "onlyexp=1" not "onlyexp=PNU001" for example.
# Since our Calibration database gets updated frequently, we ran into the problem that new calibration files only like the latest SAS. As it is very problematic to just install the new SAS, there is a workaround. You have to address the calibration files that are working with our SAS version until the new SAS is installed (we must be patient as this is not trivial). The following, however, works perfectly:

example:

#!/bin/csh
${XMMTOOLS}/xmmprepare --datadir=/eu/X-ray/XMM/data/2290/0679780201/odf/
--prepdir=./test --pn --analysisdate=2014-01-11T01:05:00.000

== XMM OM Data Extraction ==

For extracting the data of the Optical Monitor (OM) onboard XMM, there exist three tools which do this automatically: ''omichain'', ''omfchain'' and ''omgchain''.
"i" stands for image mode, "f" for fast mode and "g" for grism mode. Which mode you have can be found on the XMM log browse site: http://xmm2.esac.esa.int/external/xmm_obs_info/obs_view_frame.shtml.
If you want to extract your images you first have to set some paths:

$source $SOFTDIR/sas_init.csh
$setenv SAS_ODF path_to_your_data #normally /eu/X-ray/XMM/data/rev/ObsID/odf/
$cifbuild
$setenv SAS_CCF ccf.cif
$odfingest
$setenv SAS_ODF `ls -1 *SUM.SAS`

After this you can run

$omichain #or omfchain, omgchain

You can also do the extraction step-by-step. For a description see http://xmm.esac.esa.int/sas/current/documentation/threads/omi_stepbystep.shtml.
At the end you should have several images (<code>*IMAGE*</code>), region files (<code>*REGION*</code>) and source lists (<code>*SWSRLI*</code>) for the OM exposures and filters. The nomenclatur for the files are:

* IOOOOOOOOOODDUEEETTTTTTSXXX.FFF or POOOOOOOOOODDUEEETTTTTTSXXX.FFF (for PPS product files)
* OOOOOOOOOO = XMM-ObsID (10 characters)
* DD = Data source idetifier (here OM)
* U = exposure flag (S = sched, U = unsched, X = not aplicable)
* EEE = exposure number within the instrument observation (3 characters)
* TTTTTT = product type (6 characters)
* S = 0 or data subset number/character
* XXX = source number or slew step number (3 characters)
* FFF = file format (3 characters)

From all exposures for one filter a mosaiced sky image is produced which contains *SIMAG?.FIT. The ? stands for the filter: L = UVW1, M = UVM2, S = UVW2, B = B, U = U, V = V.
Open the image with ds9 and have a look if your source is seen and where it is. You can check this by loading a region file, produced e.g. by simbad2ds9, into the image.

Then check the detector images (<code>P*IMAGE_*000.FIT</code>) for your source (it can be, that some detector images don't contain your source because the window was off). Load the region file which belongs to the detector image (<code>*REGION*000.ASC</code>, e.g. <code>P0090050801OMS006IMAGE_0000.FIT</code> -> ''I0090050801OMS006REGION0000.ASC</code>) and identify the number of your source.

[[File:image_region.jpeg|thumb]]

Look into the source list for your exposure (<code>P*SWSRLI*.FIT</code>) and note the SRC_ID in the last column. Open the combined source list (<code>*COMBO*</code>) and search for your SRC_ID. Here you can find all the magnitudes and fluxes of your source for the different filters.

== Choosing correct XMM-EPIC filter ==

Choosing the correct EPIC filter for your observation depends on the
visual magnitudes of the other objects (usually stars) in the EPIC
field of view.

The XMM user's handbook (sect. 3.3.6;
http://xmm.esac.esa.int/external/xmm_user_support/documentation/uhb/epicfilters.html) recommends:

Thick filter: suppress up to magnitudes of -2 to -1 (pn), or +1 to +4 (mos)

Medium filter: if there is nothing above magnitude ~ 6 to 9

Thin filter: for point sources that are 12 mag fainter than thick filter limitations

The UHB notes that these magnitudes apply when you use the full frame mode; if you use a partial window mode, then sources up to 2-3 magnitudes brighter than these values should be okay.

Use the United States Naval Observatory catalog at
http://www.nofs.navy.mil/data/fchpix/ to find the stars within a 9'
radius.

At that website, enter your R.A. and Decl., and for the output file
options in the left column, unclick everything except RA,DEC,
magnitude, and offset from center. Then click 'retrieve data' in the
right column.

Next window: Click on "USNO B1.0 Star List" to download a gzipped
ASCII file with typically hundreds of rows/stars for lines of sight
away from the Galactic Plane (or many thousands of rows/stars for
lines of sight in the Galactic Plane).

Example file: See /home/markowitz/proposals/xmm2014/GS1826USNO for a
Galactic XRB, GS1826, located in the Galactic Bulge (optically-crowded
fields).

The star list is ordered by R.A., and but you can then re-order the ASCII list
by magnitude, e.g.,

cat GS1826USNO | grep -v '#' | awk '{print $7 " " $12}' | sort -g > starlist_sortB
cat GS1826USNO | grep -v '#' | awk '{print $8 " " $12}' | sort -g > starlist_sortR

since the B and R magnitudes are columns 7 and 8, and distance from the center
of f.o.v. (in arcsec) is column 12

Ignore the rows with zero magnitudes; a zero means unmeasured flux.

For these example files, e.g., /home/markowitz/proposals/xmm2014/starlist_sortB
we see that the brightest B- and R-band magnitudes are 10.0-10.3, including some
objects that are only 3-5' from the center, and at least one that's only 1.2'
from the center, so one cannot use the thin epic filter; one must use
the MEDIUM filter for all three EPIC cameras.

== XMM ESAS ==

If you are interested in diffuse X-ray emission it is recommended to use the XMM-Newton Extended Source Analysis Software.
The manual can be found at [https://heasarc.gsfc.nasa.gov/docs/xmm/esas/cookbook/xmm-esas.html] with very detailed step-by-step instructions.

==== Working with XMM ESAS in the remeis environment ====

Before you start with the data analysis you have to source the SAS init via '''source $SOFTDIR/sas_init.csh'''.
Since you will need this every time you start a new terminal it is recommended to add an alias to your .cshrc in your home directory, e.g. '''alias setsas 'source $SOFTDIR/sas_init.csh''''.

First you have to find out the observation data path in the archives, which can be done by typing '''find /eu/X-ray/xmm/data/????/obsID/odf -type d''', where you replace obsID with your desired observation.
Next, you have to set up the environment variables for the SAS tasks to function properly.

Create an analysis directory somewhere in your userdata (usually one analyzed observation has > 1 GB so don't use your home).
Set the following environment variables:

setenv SAS_ODF DIR - where DIR is the observation data path from above.
setenv SAS_CCF ANALYSIS_DIR/ccf.cif - where ANALYSIS_DIR is your directory for the analysis (on userdata), you have to add '/ccf.cif' to this path. This will create the ccf.cif file in your directory when running cifbuild
setenv CALDB_ESAS /userdata/data/knies/XMM/CALDB_ESAS (*)
* You need additional calibration files for ESAS. The latest version can be found at /userdata/data/knies/XMM/CALDB_ESAS. Please use this directory instead of downloading it again to safe disk space.

Next you have to run the basic tasks to prepare the data, but with some different options since we are working in the remeis environment:

cifbuild withccfpath=no analysisdate=now category=XMMCCF calindexset=$SAS_CCF fullpath=yes
odfingest outdir=ANALYSIS_DIR

''Important'': you can't move your files after running these steps or you will get errors.

After odfingest is finished there should be a file ending with "SUM.SAS" in your directory. Note the filename and re-set the SAS_ODF variable:

setenv SAS_ODF ANALYSIS_DIR/*SUM.SAS - replace *SUM.SAS with the filename in your directory

After this step you can follow the ESAS manual normally, starting with [https://heasarc.gsfc.nasa.gov/docs/xmm/esas/cookbook/xmm-esas.html#SECTION00082000000000000000].
Note that you have to do cifbuild and odfingest only once (and also when SAS was updated) but you have to set the environment variables each time you open a new terminal.
You can make a small shell script which you can execute each time before you continue your analysis to speed this up, e.g.:

#!/bin/tcsh -f
source $SOFTDIR/sas_init.csh
setenv SAS_ODF ANALYSIS_DIR/*SUM.SAS
setenv SAS_CCF ANALYSIS_DIR/ccf.cif
setenv CALDB_ESAS /userdata/data/knies/XMM/CALDB_ESAS

Replace the directories etc. like shown above, make your script executable with chmod +x scriptfile and then execute it with ./scriptfile.

[[Category:Data Extraction]]

Zotero

2023-11-21T13:43:45Z

Wilms:

== Zotero - a reference manager ==

=== Why use a reference manager? ===

When doing research, you will very quickly amass a large number of papers and other publications that are useful for your research (as a rule of thumb, if you're reading less than 1-2 papers per day, you are not reading enough). While you may think that you will remember where you read something, this is not true, and therefore you will soon need some way to store all of that information. While online services such as the ADS provide you with some way to collect papers in "libraries", they provide little flexibility, often cannot be fine tuned to your needs (e.g., having hierarchical structures of libraries), often do not provide a way to annotate the publication or leave other notes with the paper, and they do not work when you are offline (e.g., on the train between Wuerzburg and Frankfurt, or on a plane). In addition, keeping other publication lists such as files for bibtex up to date is difficult with these online sources.

A reference manager such as zotero is a very good way to solve all of these problems.

On this page I (J. Wilms) explain how I structure my zotero collection.

=== Installing zotero and its plugins ===

==== General Installation ====

* If it is not available, download zotero for your operating system from the [https://www.zotero.org/ Zotero web pages]. On the Remeis cluster, just activate it with '''module load zotero'''.

* On the zotero download page, it will also offer you to install the Zotero Connector for your browser. Install it and give it permission to access the pages you are browsing. The connector is a browser plugin that provides a one-click download of pdf and the bibliographic information from any online source that it recognizes, as well as getting information from PDFs and normal webpages. It only works while zotero is running as well.

* For a smooth experience that works well in astronomy, download the following plugins from the [https://www.zotero.org/support/plugins list of zotero plugins]: Better BibTex, ZotFile, and optionally the Storage Scanner for Zotero.

=== Zotero configuration ===

To configure zotero, go to Edit->Preferences. The following Image shows my General setup, I have left the other values at their default settings (although you might want to change the data directory location in Advanced->Files and Folders ).

[[File:zotero_1.png||recommended general options for zotero]]

==== ZotFile Configuration ====

Next, configure ZotFiles. This plugin can automatically recognize new PDFs in a Source folder and it can also copy new files to a pdf library that is outside of zotero. This is advantageous since it keeps the zotero storage small such that you can use zotero's online library to move the zotero database around. It also makes your life easier since it is also possible to access PDFs directly if necessary. For ZotFile I use the following settings:

* Source Folder for Attaching New Files: I use '''~/Downloads'''
* Location of Files: Use "Custom Location" and set it to the path where you want to store the PDFs.
* Tick on "User subfolder defined by" and set the field to '''/%y''' . This will sort your media according to the year of publication into subfolders.
* On the tab "Renaming Rules":
** switch off "User Zotero to Rename"
** change "Format for all Item Types except Patents to '''%a_%y_%t''' . This gives filenames consisting of the first author, year of publication, and the abbreviated title of the publication (I find leaving the year in the filename useful in case I need to use the file elsewhere).
** In the additional settings I have '''_''' as the Delimiter between multiple authors and I have ticked "Change to lower case", "Replace blanks", "Truncate title after . or : or ?". Maximum length of title 30 (you might want to shorten this!), maximum number of authors at 1, and I switch off "Add suffix when authors are omitted".

* On the tab "Advanced Settings" I set:
** Automatically rename new attachments to "Always Rename"
** ask for batch rename for 2 or more attachments
** remove special characters from filename

==== Better BibTex Configuration ====

Better BibTex will automatically generate unique bibtex tags. It also contains code to output bib-files from zotero libraries and to keep these updated whenever a new item is added to a library.

In the Better BibTeX configuration, I suggest the following:

* Citation keys:
** Citation key formula: I suggest ```auth.fold.lower+year'''. This generates citation keys consisting of the first author name and a year (postfixed with a, b, c etc. if there are multiple media from the same author in the year. I recommend using lower case names only for simplicity.
** Switch on "Force citation key to plan text"
** I do not use enable citation key search.
** Set Automatically pin citation key after 0 seconds (this ensures that citation keys are fully under control of the plugin)

* Export:
** BibTeX tab:
***switch on "Export unicode as plain-text latex commands"
*** all other check boxes are off.
*** add urls to bibtex export: "in the url field"
** BibLaTex:
*** I recommend not using BibLaTeX. This is a bit unfortunate, since BibLaTeX is a good idea in principle, but it does not scale to larger libraries and it cannot produce reference lists in the way needed by journals in astronomy and astrophysics.
** Fields:
*** export language as langid
*** when an item has both a DOI and a URL, export both
*** fields to omit from export: ```abstract,file,urldate,keywords,issn,language,url,shorttitle,copyright''' (although you might want to leave the url in the bibtex)
*** Include JabRef-specific metadata: no
** Quick-Copy:
*** I do not use this, so I left things at their default values
** postscript
*** This is javascript code that is used to manipulate the generated bibfile. The following code will generate journal fields with LaTeX-commands appropriate for astrophysical journal styles.

<pre>
if (Translator.BetterBibTeX) {
if (reference.has.journal) {
switch(item.publicationTitle) {
case "Acta Astronomica":
reference.add({name: 'journal', value: "\\actaa", enc: 'raw'});
break;
case "Advances in Space Research":
reference.add({name: 'journal', value: "Adv.\ Space Res.", enc: 'raw'});
break;
case "The Astronomical Journal":
reference.add({name: 'journal', value: "\\aj", enc: 'raw'});
break;
case "Annual Review of Astronomy and Astrophysics":
reference.add({name: 'journal', value: "\\araa", enc: 'raw'});
break;
case "Astrophysical Letters and Communications":
reference.add({name: 'journal', value: "\\aplett", enc: 'raw'});
break;
case "Astrophysical Journal":
case "The Astrophysical Journal":
case "The Astrophysical Journal Letters":
case "The Astrophysical Journal, Letters":
reference.add({name: 'journal', value: "\\apj", enc: 'raw'});
break;
case "The Astrophysical Journal Supplement Series":
case "The Astrophysical Journal, Supplement":
reference.add({name: 'journal', value: "\\apjs", enc: 'raw'});
break;
case "Applied Optics":
reference.add({name: 'journal', value: "\\ao", enc: 'raw'});
break;
case "Astrophysics Letters":
reference.add({name: 'journal', value: "\\aplett", enc: 'raw'});
break;
case "Astrophysics and Space Physics Research":
reference.add({name: 'journal', value: "\\apspr", enc: 'raw'});
break;
case "Astrophysics and Space Science":
reference.add({name: 'journal', value: "\\apss", enc: 'raw'});
break;
case "Astronomy and Astrophysics":
case "Astronomy & Astrophysics":
reference.add({name: 'journal', value: "\\aap", enc: 'raw'});
break;
case "Astronomy & Astrophysics Reviews":
case "The Astronomy & Astrophysics Reviews":
reference.add({name: 'journal', value: "\\aapr", enc: 'raw'});
break;
case "Astronomy & Astrophysics Supplement":
case "Astronomy and Astrophysics Supplement Series":
reference.add({name: 'journal', value: "\\aaps", enc: 'raw'});
break;
case "Astronomicheskii Zhurnal":
reference.add({name: 'journal', value: "\\azh", enc: 'raw'});
break;
case "Bulletin of the AAS":
reference.add({name: 'journal', value: "\\baas", enc: 'raw'});
break;
case "Bulletin of the Astronomical Institutes of Czechoslovakia":
reference.add({name: 'journal', value: "\\bac", enc: 'raw'});
break;
case "Bulletin of the Astronomical Institute of the Netherlands":
reference.add({name: 'journal', value: "\\bain", enc: 'raw'});
break;
case "Chinese Astronomy and Astrophysics":
reference.add({name: 'journal', value: "\\caa", enc: 'raw'});
break;
case "Chinese Journal of Astronomy and Astrophysics":
reference.add({name: 'journal', value: "\\cjaa", enc: 'raw'});
break;
case "Fundamental Cosmic Physics":
reference.add({name: 'journal', value: "\\fcp", enc: 'raw'});
break;
case "Geochimica Cosmochimica Acta":
reference.add({name: 'journal', value: "\\gca", enc: 'raw'});
break;
case "Geophysics Research Letters":
reference.add({name: 'journal', value: "\\grl", enc: 'raw'});
break;
case "IAU Circular":
reference.add({name: 'journal', value: "\\iaucirc", enc: 'raw'});
break;
case "Icarus":
reference.add({name: 'journal', value: "\\icarus", enc: 'raw'});
break;
case "Journal of Cosmology and Astroparticle Physics":
reference.add({name: 'journal', value: "\\jcap", enc: 'raw'});
break;
case "Journal of Chemical Physics":
reference.add({name: 'journal', value: "\\jcp", enc: 'raw'});
break;
case "Journal of Geophysics Research":
reference.add({name: 'journal', value: "\\jgr", enc: 'raw'});
break;
case "Journal of Low Temperature Physics":
case "J Low Temp Phys":
reference.add({name: 'journal', value: "J.\\ Low Temp.\\ Phys.", enc: 'raw'});
break;
case "Journal of Quantitative Spectroscopy and Radiative Transfer":
reference.add({name: 'journal', value: "\\jsqrt", enc: 'raw'});
break;
case "Journal of the Royal Astronomical Society of Canada":
reference.add({name: 'journal', value: "\\jrasc", enc: 'raw'});
break;
case "Memoirs of the Royal Astronomical Society":
reference.add({name: 'journal', value: "\\memras", enc: 'raw'});
break;
case "Monthly Notices of the Royal Astronomical Society":
reference.add({name: 'journal', value: "\\mnras", enc: 'raw'});
break;
case "Monthly Notices of the Royal Astronomical Society: Letters":
reference.add({name: 'journal', value: "\\mnras", enc: 'raw'});
break;
case "Memorie Societa Astronomica Italiana":
reference.add({name: 'journal', value: "\\memsai", enc: 'raw'});
break;
case "New Astronomy":
reference.add({name: 'journal', value: "\\na", enc: 'raw'});
break;
case "Nuclear Physics A":
reference.add({name: 'journal', value: "\\nphysa", enc: 'raw'});
break;
case "Physical Review A":
reference.add({name: 'journal', value: "\\pra", enc: 'raw'});
break;
case "Physical Review B":
reference.add({name: 'journal', value: "\\prb", enc: 'raw'});
break;
case "Physical Review C":
reference.add({name: 'journal', value: "\\prc", enc: 'raw'});
break;
case "Physical Review D":
reference.add({name: 'journal', value: "\\prd", enc: 'raw'});
break;
case "Physical Review E":
reference.add({name: 'journal', value: "\\pre", enc: 'raw'});
break;
case "Physical Review Letters":
reference.add({name: 'journal', value: "\\prl", enc: 'raw'});
break;
case "Publications of the Astronomical Society of the Pacific":
reference.add({name: 'journal', value: "\\pasp", enc: 'raw'});
break;
case "Publications of the Astronomical Society of Japan":
reference.add({name: 'journal', value: "\\pasj", enc: 'raw'});
break;
case "Publications of the Astronomical Society of Australia":
reference.add({name: 'journal', value: "\\pasa", enc: 'raw'});
break;
case "Physics Reports":
reference.add({name: 'journal', value: "\\physrep", enc: 'raw'});
break;
case "Physica Scripta":
reference.add({name: 'journal', value: "\\physscr", enc: 'raw'});
break;
case "Planetary Space Science":
reference.add({name: 'journal', value: "\\planss", enc: 'raw'});
break;
case "Proceedings of the SPIE":
reference.add({name: 'journal', value: "\\procspie", enc: 'raw'});
break;
case "Quarterly Journal of the Royal Astronomical Society":
reference.add({name: 'journal', value: "\\qjras", enc: 'raw'});
break;
case "Revista Mexicana de Astronomia y Astrofisica":
reference.add({name: 'journal', value: "\\rmxaa", enc: 'raw'});
break;
case "Sky and Telescope":
reference.add({name: 'journal', value: "\\skytel", enc: 'raw'});
break;
case "Solar Physics":
reference.add({name: 'journal', value: "\\solphys", enc: 'raw'});
break;
case "Soviet Astronomy":
reference.add({name: 'journal', value: "\\sovast", enc: 'raw'});
break;
case "Space Science Reviews":
reference.add({name: 'journal', value: "\\ssr", enc: 'raw'});
break;
case "Zeitschrift für Astrophysik":
reference.add({name: 'journal', value: "\\zap", enc: 'raw'});
break;
}
}
}
</pre>

(NB you can also set individual journal abbreviations in the entries for individual articles; this is recommended for journals not in the above list)

* Tab list continued
**Miscellaneous
*** switch off "automatically abbreviate journal title" and "include comments about potential problems"
*** turn on "include automatic tags in export"
*** when converting to plan text latex: "Minimize the number of switches between math-mode and text-mode"
*** switch on apply title-casing to titles
*** switch on apply case-protection to capitalized words by enclosing them in braces"

* Automatic export: set "on change" to no - this will keep your bibfiles updated

=== General recommendations ===

These are a few additional comments on how I use zotero:

* When writing a paper I generate a new library and copy the references there. This is mainly because my zotero library is very large (more than 6000 individual papers). In most cases, keep things that belong together in the same library (e.g., all neutron star papers in a "neutron star" library, all AGN papers in an "AGN" library).

* Use sublibraries to structure things (e.g., I have libraries for individual sources)

* papers can be in multiple libraries (so if a paper is, e.g., on accretion in a specific source but also contains interesting thoughts about accretion in general, it will be in both, the "accretion library" and the source specific library.

* keep bibfiles in sync for those libraries pertinent to a project you're working on. You do this by pressing the right mouse button and export the collection using "Better Bibtex". Enable "use journal abbreviation", "keep updated", and "background export". Do NOT enable "Export notes" and "Export Files".

* SPIE papers are not exported correctly from the ADS. Go to the journal page at SPIE and get the PDF from there. You might want to check that the editors and conference are set correctly. If not, add them by hand (add a new author and then switch from "Author" to "Editor".

[[Category:Software]]

Zotero

2023-11-21T13:40:24Z

Wilms:

== Zotero - a reference manager ==

=== Why use a reference manager? ===

When doing research, you will very quickly amass a large number of papers and other publications that are useful for your research (as a rule of thumb, if you're reading less than 1-2 papers per day, you are not reading enough). While you may think that you will remember where you read something, this is not true, and therefore you will soon need some way to store all of that information. While online services such as the ADS provide you with some way to collect papers in "libraries", they provide little flexibility, often cannot be fine tuned to your needs (e.g., having hierarchical structures of libraries), often do not provide a way to annotate the publication or leave other notes with the paper, and they do not work when you are offline (e.g., on the train between Wuerzburg and Frankfurt, or on a plane). In addition, keeping other publication lists such as files for bibtex up to date is difficult with these online sources.

A reference manager such as zotero is a very good way to solve all of these problems.

On this page I (J. Wilms) explain how I structure my zotero collection.

=== Installing zotero ===

* If it is not available, download zotero for your operating system from the [https://www.zotero.org/ Zotero web pages]. On the Remeis cluster, just activate it with '''module load zotero'''.

* On the zotero download page, it will also offer you to install the Zotero Connector for your browser. Install it and give it permission to access the pages you are browsing. The connector is a browser plugin that provides a one-click download of pdf and the bibliographic information from any online source that it recognizes, as well as getting information from PDFs and normal webpages. It only works while zotero is running as well.

* For a smooth experience that works well in astronomy, download the following plugins from the [https://www.zotero.org/support/plugins list of zotero plugins]: Better BibTex, ZotFile, and optionally the Storage Scanner for Zotero.

=== Zotero configuration ===

To configure zotero, go to Edit->Preferences. The following Image shows my General setup, I have left the other values at their default settings (although you might want to change the data directory location in Advanced->Files and Folders ).

[[File:zotero_1.png||recommended general options for zotero]]

=== ZotFile Configuration ===

Next, configure ZotFiles. This plugin can automatically recognize new PDFs in a Source folder and it can also copy new files to a pdf library that is outside of zotero. This is advantageous since it keeps the zotero storage small such that you can use zotero's online library to move the zotero database around. It also makes your life easier since it is also possible to access PDFs directly if necessary. For ZotFile I use the following settings:

* Source Folder for Attaching New Files: I use '''~/Downloads'''
* Location of Files: Use "Custom Location" and set it to the path where you want to store the PDFs.
* Tick on "User subfolder defined by" and set the field to '''/%y''' . This will sort your media according to the year of publication into subfolders.
* On the tab "Renaming Rules":
** switch off "User Zotero to Rename"
** change "Format for all Item Types except Patents to '''%a_%y_%t''' . This gives filenames consisting of the first author, year of publication, and the abbreviated title of the publication (I find leaving the year in the filename useful in case I need to use the file elsewhere).
** In the additional settings I have '''_''' as the Delimiter between multiple authors and I have ticked "Change to lower case", "Replace blanks", "Truncate title after . or : or ?". Maximum length of title 30 (you might want to shorten this!), maximum number of authors at 1, and I switch off "Add suffix when authors are omitted".

* On the tab "Advanced Settings" I set:
** Automatically rename new attachments to "Always Rename"
** ask for batch rename for 2 or more attachments
** remove special characters from filename

=== Better BibTex Configuration ===

Better BibTex will automatically generate unique bibtex tags. It also contains code to output bib-files from zotero libraries and to keep these updated whenever a new item is added to a library.

In the Better BibTeX configuration, I suggest the following:

* Citation keys:
** Citation key formula: I suggest ```auth.fold.lower+year'''. This generates citation keys consisting of the first author name and a year (postfixed with a, b, c etc. if there are multiple media from the same author in the year. I recommend using lower case names only for simplicity.
** Switch on "Force citation key to plan text"
** I do not use enable citation key search.
** Set Automatically pin citation key after 0 seconds (this ensures that citation keys are fully under control of the plugin)

* Export:
** BibTeX tab:
***switch on "Export unicode as plain-text latex commands"
*** all other check boxes are off.
*** add urls to bibtex export: "in the url field"
** BibLaTex:
*** I recommend not using BibLaTeX. This is a bit unfortunate, since BibLaTeX is a good idea in principle, but it does not scale to larger libraries and it cannot produce reference lists in the way needed by journals in astronomy and astrophysics.
** Fields:
*** export language as langid
*** when an item has both a DOI and a URL, export both
*** fields to omit from export: ```abstract,file,urldate,keywords,issn,language,url,shorttitle,copyright''' (although you might want to leave the url in the bibtex)
*** Include JabRef-specific metadata: no
** Quick-Copy:
*** I do not use this, so I left things at their default values
** postscript
*** This is javascript code that is used to manipulate the generated bibfile. The following code will generate journal fields with LaTeX-commands appropriate for astrophysical journal styles.

<pre>
if (Translator.BetterBibTeX) {
if (reference.has.journal) {
switch(item.publicationTitle) {
case "Acta Astronomica":
reference.add({name: 'journal', value: "\\actaa", enc: 'raw'});
break;
case "Advances in Space Research":
reference.add({name: 'journal', value: "Adv.\ Space Res.", enc: 'raw'});
break;
case "The Astronomical Journal":
reference.add({name: 'journal', value: "\\aj", enc: 'raw'});
break;
case "Annual Review of Astronomy and Astrophysics":
reference.add({name: 'journal', value: "\\araa", enc: 'raw'});
break;
case "Astrophysical Letters and Communications":
reference.add({name: 'journal', value: "\\aplett", enc: 'raw'});
break;
case "Astrophysical Journal":
case "The Astrophysical Journal":
case "The Astrophysical Journal Letters":
case "The Astrophysical Journal, Letters":
reference.add({name: 'journal', value: "\\apj", enc: 'raw'});
break;
case "The Astrophysical Journal Supplement Series":
case "The Astrophysical Journal, Supplement":
reference.add({name: 'journal', value: "\\apjs", enc: 'raw'});
break;
case "Applied Optics":
reference.add({name: 'journal', value: "\\ao", enc: 'raw'});
break;
case "Astrophysics Letters":
reference.add({name: 'journal', value: "\\aplett", enc: 'raw'});
break;
case "Astrophysics and Space Physics Research":
reference.add({name: 'journal', value: "\\apspr", enc: 'raw'});
break;
case "Astrophysics and Space Science":
reference.add({name: 'journal', value: "\\apss", enc: 'raw'});
break;
case "Astronomy and Astrophysics":
case "Astronomy & Astrophysics":
reference.add({name: 'journal', value: "\\aap", enc: 'raw'});
break;
case "Astronomy & Astrophysics Reviews":
case "The Astronomy & Astrophysics Reviews":
reference.add({name: 'journal', value: "\\aapr", enc: 'raw'});
break;
case "Astronomy & Astrophysics Supplement":
case "Astronomy and Astrophysics Supplement Series":
reference.add({name: 'journal', value: "\\aaps", enc: 'raw'});
break;
case "Astronomicheskii Zhurnal":
reference.add({name: 'journal', value: "\\azh", enc: 'raw'});
break;
case "Bulletin of the AAS":
reference.add({name: 'journal', value: "\\baas", enc: 'raw'});
break;
case "Bulletin of the Astronomical Institutes of Czechoslovakia":
reference.add({name: 'journal', value: "\\bac", enc: 'raw'});
break;
case "Bulletin of the Astronomical Institute of the Netherlands":
reference.add({name: 'journal', value: "\\bain", enc: 'raw'});
break;
case "Chinese Astronomy and Astrophysics":
reference.add({name: 'journal', value: "\\caa", enc: 'raw'});
break;
case "Chinese Journal of Astronomy and Astrophysics":
reference.add({name: 'journal', value: "\\cjaa", enc: 'raw'});
break;
case "Fundamental Cosmic Physics":
reference.add({name: 'journal', value: "\\fcp", enc: 'raw'});
break;
case "Geochimica Cosmochimica Acta":
reference.add({name: 'journal', value: "\\gca", enc: 'raw'});
break;
case "Geophysics Research Letters":
reference.add({name: 'journal', value: "\\grl", enc: 'raw'});
break;
case "IAU Circular":
reference.add({name: 'journal', value: "\\iaucirc", enc: 'raw'});
break;
case "Icarus":
reference.add({name: 'journal', value: "\\icarus", enc: 'raw'});
break;
case "Journal of Cosmology and Astroparticle Physics":
reference.add({name: 'journal', value: "\\jcap", enc: 'raw'});
break;
case "Journal of Chemical Physics":
reference.add({name: 'journal', value: "\\jcp", enc: 'raw'});
break;
case "Journal of Geophysics Research":
reference.add({name: 'journal', value: "\\jgr", enc: 'raw'});
break;
case "Journal of Low Temperature Physics":
case "J Low Temp Phys":
reference.add({name: 'journal', value: "J.\\ Low Temp.\\ Phys.", enc: 'raw'});
break;
case "Journal of Quantitative Spectroscopy and Radiative Transfer":
reference.add({name: 'journal', value: "\\jsqrt", enc: 'raw'});
break;
case "Journal of the Royal Astronomical Society of Canada":
reference.add({name: 'journal', value: "\\jrasc", enc: 'raw'});
break;
case "Memoirs of the Royal Astronomical Society":
reference.add({name: 'journal', value: "\\memras", enc: 'raw'});
break;
case "Monthly Notices of the Royal Astronomical Society":
reference.add({name: 'journal', value: "\\mnras", enc: 'raw'});
break;
case "Monthly Notices of the Royal Astronomical Society: Letters":
reference.add({name: 'journal', value: "\\mnras", enc: 'raw'});
break;
case "Memorie Societa Astronomica Italiana":
reference.add({name: 'journal', value: "\\memsai", enc: 'raw'});
break;
case "New Astronomy":
reference.add({name: 'journal', value: "\\na", enc: 'raw'});
break;
case "Nuclear Physics A":
reference.add({name: 'journal', value: "\\nphysa", enc: 'raw'});
break;
case "Physical Review A":
reference.add({name: 'journal', value: "\\pra", enc: 'raw'});
break;
case "Physical Review B":
reference.add({name: 'journal', value: "\\prb", enc: 'raw'});
break;
case "Physical Review C":
reference.add({name: 'journal', value: "\\prc", enc: 'raw'});
break;
case "Physical Review D":
reference.add({name: 'journal', value: "\\prd", enc: 'raw'});
break;
case "Physical Review E":
reference.add({name: 'journal', value: "\\pre", enc: 'raw'});
break;
case "Physical Review Letters":
reference.add({name: 'journal', value: "\\prl", enc: 'raw'});
break;
case "Publications of the Astronomical Society of the Pacific":
reference.add({name: 'journal', value: "\\pasp", enc: 'raw'});
break;
case "Publications of the Astronomical Society of Japan":
reference.add({name: 'journal', value: "\\pasj", enc: 'raw'});
break;
case "Publications of the Astronomical Society of Australia":
reference.add({name: 'journal', value: "\\pasa", enc: 'raw'});
break;
case "Physics Reports":
reference.add({name: 'journal', value: "\\physrep", enc: 'raw'});
break;
case "Physica Scripta":
reference.add({name: 'journal', value: "\\physscr", enc: 'raw'});
break;
case "Planetary Space Science":
reference.add({name: 'journal', value: "\\planss", enc: 'raw'});
break;
case "Proceedings of the SPIE":
reference.add({name: 'journal', value: "\\procspie", enc: 'raw'});
break;
case "Quarterly Journal of the Royal Astronomical Society":
reference.add({name: 'journal', value: "\\qjras", enc: 'raw'});
break;
case "Revista Mexicana de Astronomia y Astrofisica":
reference.add({name: 'journal', value: "\\rmxaa", enc: 'raw'});
break;
case "Sky and Telescope":
reference.add({name: 'journal', value: "\\skytel", enc: 'raw'});
break;
case "Solar Physics":
reference.add({name: 'journal', value: "\\solphys", enc: 'raw'});
break;
case "Soviet Astronomy":
reference.add({name: 'journal', value: "\\sovast", enc: 'raw'});
break;
case "Space Science Reviews":
reference.add({name: 'journal', value: "\\ssr", enc: 'raw'});
break;
case "Zeitschrift für Astrophysik":
reference.add({name: 'journal', value: "\\zap", enc: 'raw'});
break;
}
}
}
</pre>

(NB you can also set individual journal abbreviations in the entries for individual articles; this is recommended for journals not in the above list)

* Tab list continued
**Miscellaneous
*** switch off "automatically abbreviate journal title" and "include comments about potential problems"
*** turn on "include automatic tags in export"
*** when converting to plan text latex: "Minimize the number of switches between math-mode and text-mode"
*** switch on apply title-casing to titles
*** switch on apply case-protection to capitalized words by enclosing them in braces"

* Automatic export: set "on change" to no - this will keep your bibfiles updated

== General recommendations for zotero ==

These are a few additional comments on how I use zotero:

* When writing a paper I generate a new library and copy the references there. This is mainly because my zotero library is very large (more than 6000 individual papers). In most cases, keep things that belong together in the same library (e.g., all neutron star papers in a "neutron star" library, all AGN papers in an "AGN" library).

* Use sublibraries to structure things (e.g., I have libraries for individual sources)

* papers can be in multiple libraries (so if a paper is, e.g., on accretion in a specific source but also contains interesting thoughts about accretion in general, it will be in both, the "accretion library" and the source specific library.

* keep bibfiles in sync for those libraries pertinent to a project you're working on. You do this by pressing the right mouse button and export the collection using "Better Bibtex". Enable "use journal abbreviation", "keep updated", and "background export". Do NOT enable "Export notes" and "Export Files".

* SPIE papers are not exported correctly from the ADS. Go to the journal page at SPIE and get the PDF from there. You might want to check that the editors and conference are set correctly. If not, add them by hand (add a new author and then switch from "Author" to "Editor".

Zotero

2023-11-21T13:38:28Z

Wilms: /* Zotero and plugin installation */

== Zotero - a reference manager ==

=== Why use a reference manager? ===

When doing research, you will very quickly amass a large number of papers and other publications that are useful for your research (as a rule of thumb, if you're reading less than 1-2 papers per day, you are not reading enough). While you may think that you will remember where you read something, this is not true, and therefore you will soon need some way to store all of that information. While online services such as the ADS provide you with some way to collect papers in "libraries", they provide little flexibility, often cannot be fine tuned to your needs (e.g., having hierarchical structures of libraries), often do not provide a way to annotate the publication or leave other notes with the paper, and they do not work when you are offline (e.g., on the train between Wuerzburg and Frankfurt, or on a plane). In addition, keeping other publication lists such as files for bibtex up to date is difficult with these online sources.

A reference manager such as zotero is a very good way to solve all of these problems.

On this page I (J. Wilms) explain how I structure my zotero collection.

=== Installing zotero ===

==== Zotero and plugin installation ====

* If it is not available, download zotero for your operating system from the [https://www.zotero.org/ Zotero web pages]. On the Remeis cluster, just activate it with '''module load zotero'''.

* On the zotero download page, it will also offer you to install the Zotero Connector for your browser. Install it and give it permission to access the pages you are browsing. The connector is a browser plugin that provides a one-click download of pdf and the bibliographic information from any online source that it recognizes, as well as getting information from PDFs and normal webpages. It only works while zotero is running as well.

* For a smooth experience that works well in astronomy, download the following plugins from the [https://www.zotero.org/support/plugins list of zotero plugins]: Better BibTex, ZotFile, and optionally the Storage Scanner for Zotero.

=== Zotero configuration ===

To configure zotero, go to Edit->Preferences. The following Image shows my General setup, I have left the other values at their default settings (although you might want to change the data directory location in Advanced->Files and Folders ).

[[File:zotero_1.png||recommended general options for zotero]]

=== ZotFile Configuration ===

Next, configure ZotFiles. This plugin can automatically recognize new PDFs in a Source folder and it can also copy new files to a pdf library that is outside of zotero. This is advantageous since it keeps the zotero storage small such that you can use zotero's online library to move the zotero database around. It also makes your life easier since it is also possible to access PDFs directly if necessary. For ZotFile I use the following settings:

* Source Folder for Attaching New Files: I use '''~/Downloads'''
* Location of Files: Use "Custom Location" and set it to the path where you want to store the PDFs.
* Tick on "User subfolder defined by" and set the field to '''/%y''' . This will sort your media according to the year of publication into subfolders.
* On the tab "Renaming Rules":
** switch off "User Zotero to Rename"
** change "Format for all Item Types except Patents to '''%a_%y_%t''' . This gives filenames consisting of the first author, year of publication, and the abbreviated title of the publication (I find leaving the year in the filename useful in case I need to use the file elsewhere).
** In the additional settings I have '''_''' as the Delimiter between multiple authors and I have ticked "Change to lower case", "Replace blanks", "Truncate title after . or : or ?". Maximum length of title 30 (you might want to shorten this!), maximum number of authors at 1, and I switch off "Add suffix when authors are omitted".

* On the tab "Advanced Settings" I set:
** Automatically rename new attachments to "Always Rename"
** ask for batch rename for 2 or more attachments
** remove special characters from filename

=== Better BibTex Configuration ===

Better BibTex will automatically generate unique bibtex tags. It also contains code to output bib-files from zotero libraries and to keep these updated whenever a new item is added to a library.

In the Better BibTeX configuration, I suggest the following:

* Citation keys:
** Citation key formula: I suggest ```auth.fold.lower+year'''. This generates citation keys consisting of the first author name and a year (postfixed with a, b, c etc. if there are multiple media from the same author in the year. I recommend using lower case names only for simplicity.
** Switch on "Force citation key to plan text"
** I do not use enable citation key search.
** Set Automatically pin citation key after 0 seconds (this ensures that citation keys are fully under control of the plugin)

* Export:
** BibTeX tab:
***switch on "Export unicode as plain-text latex commands"
*** all other check boxes are off.
*** add urls to bibtex export: "in the url field"
** BibLaTex:
*** I recommend not using BibLaTeX. This is a bit unfortunate, since BibLaTeX is a good idea in principle, but it does not scale to larger libraries and it cannot produce reference lists in the way needed by journals in astronomy and astrophysics.
** Fields:
*** export language as langid
*** when an item has both a DOI and a URL, export both
*** fields to omit from export: ```abstract,file,urldate,keywords,issn,language,url,shorttitle,copyright''' (although you might want to leave the url in the bibtex)
*** Include JabRef-specific metadata: no
** Quick-Copy:
*** I do not use this, so I left things at their default values
** postscript
*** This is javascript code that is used to manipulate the generated bibfile. The following code will generate journal fields with LaTeX-commands appropriate for astrophysical journal styles.

<pre>
if (Translator.BetterBibTeX) {
if (reference.has.journal) {
switch(item.publicationTitle) {
case "Acta Astronomica":
reference.add({name: 'journal', value: "\\actaa", enc: 'raw'});
break;
case "Advances in Space Research":
reference.add({name: 'journal', value: "Adv.\ Space Res.", enc: 'raw'});
break;
case "The Astronomical Journal":
reference.add({name: 'journal', value: "\\aj", enc: 'raw'});
break;
case "Annual Review of Astronomy and Astrophysics":
reference.add({name: 'journal', value: "\\araa", enc: 'raw'});
break;
case "Astrophysical Letters and Communications":
reference.add({name: 'journal', value: "\\aplett", enc: 'raw'});
break;
case "Astrophysical Journal":
case "The Astrophysical Journal":
case "The Astrophysical Journal Letters":
case "The Astrophysical Journal, Letters":
reference.add({name: 'journal', value: "\\apj", enc: 'raw'});
break;
case "The Astrophysical Journal Supplement Series":
case "The Astrophysical Journal, Supplement":
reference.add({name: 'journal', value: "\\apjs", enc: 'raw'});
break;
case "Applied Optics":
reference.add({name: 'journal', value: "\\ao", enc: 'raw'});
break;
case "Astrophysics Letters":
reference.add({name: 'journal', value: "\\aplett", enc: 'raw'});
break;
case "Astrophysics and Space Physics Research":
reference.add({name: 'journal', value: "\\apspr", enc: 'raw'});
break;
case "Astrophysics and Space Science":
reference.add({name: 'journal', value: "\\apss", enc: 'raw'});
break;
case "Astronomy and Astrophysics":
case "Astronomy & Astrophysics":
reference.add({name: 'journal', value: "\\aap", enc: 'raw'});
break;
case "Astronomy & Astrophysics Reviews":
case "The Astronomy & Astrophysics Reviews":
reference.add({name: 'journal', value: "\\aapr", enc: 'raw'});
break;
case "Astronomy & Astrophysics Supplement":
case "Astronomy and Astrophysics Supplement Series":
reference.add({name: 'journal', value: "\\aaps", enc: 'raw'});
break;
case "Astronomicheskii Zhurnal":
reference.add({name: 'journal', value: "\\azh", enc: 'raw'});
break;
case "Bulletin of the AAS":
reference.add({name: 'journal', value: "\\baas", enc: 'raw'});
break;
case "Bulletin of the Astronomical Institutes of Czechoslovakia":
reference.add({name: 'journal', value: "\\bac", enc: 'raw'});
break;
case "Bulletin of the Astronomical Institute of the Netherlands":
reference.add({name: 'journal', value: "\\bain", enc: 'raw'});
break;
case "Chinese Astronomy and Astrophysics":
reference.add({name: 'journal', value: "\\caa", enc: 'raw'});
break;
case "Chinese Journal of Astronomy and Astrophysics":
reference.add({name: 'journal', value: "\\cjaa", enc: 'raw'});
break;
case "Fundamental Cosmic Physics":
reference.add({name: 'journal', value: "\\fcp", enc: 'raw'});
break;
case "Geochimica Cosmochimica Acta":
reference.add({name: 'journal', value: "\\gca", enc: 'raw'});
break;
case "Geophysics Research Letters":
reference.add({name: 'journal', value: "\\grl", enc: 'raw'});
break;
case "IAU Circular":
reference.add({name: 'journal', value: "\\iaucirc", enc: 'raw'});
break;
case "Icarus":
reference.add({name: 'journal', value: "\\icarus", enc: 'raw'});
break;
case "Journal of Cosmology and Astroparticle Physics":
reference.add({name: 'journal', value: "\\jcap", enc: 'raw'});
break;
case "Journal of Chemical Physics":
reference.add({name: 'journal', value: "\\jcp", enc: 'raw'});
break;
case "Journal of Geophysics Research":
reference.add({name: 'journal', value: "\\jgr", enc: 'raw'});
break;
case "Journal of Low Temperature Physics":
case "J Low Temp Phys":
reference.add({name: 'journal', value: "J.\\ Low Temp.\\ Phys.", enc: 'raw'});
break;
case "Journal of Quantitative Spectroscopy and Radiative Transfer":
reference.add({name: 'journal', value: "\\jsqrt", enc: 'raw'});
break;
case "Journal of the Royal Astronomical Society of Canada":
reference.add({name: 'journal', value: "\\jrasc", enc: 'raw'});
break;
case "Memoirs of the Royal Astronomical Society":
reference.add({name: 'journal', value: "\\memras", enc: 'raw'});
break;
case "Monthly Notices of the Royal Astronomical Society":
reference.add({name: 'journal', value: "\\mnras", enc: 'raw'});
break;
case "Monthly Notices of the Royal Astronomical Society: Letters":
reference.add({name: 'journal', value: "\\mnras", enc: 'raw'});
break;
case "Memorie Societa Astronomica Italiana":
reference.add({name: 'journal', value: "\\memsai", enc: 'raw'});
break;
case "New Astronomy":
reference.add({name: 'journal', value: "\\na", enc: 'raw'});
break;
case "Nuclear Physics A":
reference.add({name: 'journal', value: "\\nphysa", enc: 'raw'});
break;
case "Physical Review A":
reference.add({name: 'journal', value: "\\pra", enc: 'raw'});
break;
case "Physical Review B":
reference.add({name: 'journal', value: "\\prb", enc: 'raw'});
break;
case "Physical Review C":
reference.add({name: 'journal', value: "\\prc", enc: 'raw'});
break;
case "Physical Review D":
reference.add({name: 'journal', value: "\\prd", enc: 'raw'});
break;
case "Physical Review E":
reference.add({name: 'journal', value: "\\pre", enc: 'raw'});
break;
case "Physical Review Letters":
reference.add({name: 'journal', value: "\\prl", enc: 'raw'});
break;
case "Publications of the Astronomical Society of the Pacific":
reference.add({name: 'journal', value: "\\pasp", enc: 'raw'});
break;
case "Publications of the Astronomical Society of Japan":
reference.add({name: 'journal', value: "\\pasj", enc: 'raw'});
break;
case "Publications of the Astronomical Society of Australia":
reference.add({name: 'journal', value: "\\pasa", enc: 'raw'});
break;
case "Physics Reports":
reference.add({name: 'journal', value: "\\physrep", enc: 'raw'});
break;
case "Physica Scripta":
reference.add({name: 'journal', value: "\\physscr", enc: 'raw'});
break;
case "Planetary Space Science":
reference.add({name: 'journal', value: "\\planss", enc: 'raw'});
break;
case "Proceedings of the SPIE":
reference.add({name: 'journal', value: "\\procspie", enc: 'raw'});
break;
case "Quarterly Journal of the Royal Astronomical Society":
reference.add({name: 'journal', value: "\\qjras", enc: 'raw'});
break;
case "Revista Mexicana de Astronomia y Astrofisica":
reference.add({name: 'journal', value: "\\rmxaa", enc: 'raw'});
break;
case "Sky and Telescope":
reference.add({name: 'journal', value: "\\skytel", enc: 'raw'});
break;
case "Solar Physics":
reference.add({name: 'journal', value: "\\solphys", enc: 'raw'});
break;
case "Soviet Astronomy":
reference.add({name: 'journal', value: "\\sovast", enc: 'raw'});
break;
case "Space Science Reviews":
reference.add({name: 'journal', value: "\\ssr", enc: 'raw'});
break;
case "Zeitschrift für Astrophysik":
reference.add({name: 'journal', value: "\\zap", enc: 'raw'});
break;
}
}
}
</pre>

(NB you can also set individual journal abbreviations in the entries for individual articles; this is recommended for journals not in the above list)

* Tab list continued
**Miscellaneous
*** switch off "automatically abbreviate journal title" and "include comments about potential problems"
*** turn on "include automatic tags in export"
*** when converting to plan text latex: "Minimize the number of switches between math-mode and text-mode"
*** switch on apply title-casing to titles
*** switch on apply case-protection to capitalized words by enclosing them in braces"

* Automatic export: set "on change" to no - this will keep your bibfiles updated

== General recommendations for zotero ==

These are a few additional comments on how I use zotero:

* When writing a paper I generate a new library and copy the references there. This is mainly because my zotero library is very large (more than 6000 individual papers). In most cases, keep things that belong together in the same library (e.g., all neutron star papers in a "neutron star" library, all AGN papers in an "AGN" library).

* Use sublibraries to structure things (e.g., I have libraries for individual sources)

* papers can be in multiple libraries (so if a paper is, e.g., on accretion in a specific source but also contains interesting thoughts about accretion in general, it will be in both, the "accretion library" and the source specific library.

* keep bibfiles in sync for those libraries pertinent to a project you're working on. You do this by pressing the right mouse button and export the collection using "Better Bibtex". Enable "use journal abbreviation", "keep updated", and "background export". Do NOT enable "Export notes" and "Export Files".

* SPIE papers are not exported correctly from the ADS. Go to the journal page at SPIE and get the PDF from there. You might want to check that the editors and conference are set correctly. If not, add them by hand (add a new author and then switch from "Author" to "Editor".

File:Zotero 1.png

2023-11-21T13:36:33Z

Wilms:

Zotero

2023-11-21T13:36:09Z

Wilms: How Joern uses Zotero

== Zotero - a reference manager ==

=== Why use a reference manager? ===

When doing research, you will very quickly amass a large number of papers and other publications that are useful for your research (as a rule of thumb, if you're reading less than 1-2 papers per day, you are not reading enough). While you may think that you will remember where you read something, this is not true, and therefore you will soon need some way to store all of that information. While online services such as the ADS provide you with some way to collect papers in "libraries", they provide little flexibility, often cannot be fine tuned to your needs (e.g., having hierarchical structures of libraries), often do not provide a way to annotate the publication or leave other notes with the paper, and they do not work when you are offline (e.g., on the train between Wuerzburg and Frankfurt, or on a plane). In addition, keeping other publication lists such as files for bibtex up to date is difficult with these online sources.

A reference manager such as zotero is a very good way to solve all of these problems.

On this page I (J. Wilms) explain how I structure my zotero collection.

=== Installing zotero ===

==== Zotero and plugin installation ====

* If it is not available, download zotero for your operating system from the [https://www.zotero.org/ Zotero web pages].

* On the zotero download page, it will also offer you to install the Zotero Connector for your browser. Install it and give it permission to access the pages you are browsing. The connector is a browser plugin that provides a one-click download of pdf and the bibliographic information from any online source that it recognizes, as well as getting information from PDFs and normal webpages. It only works while zotero is running as well.

* For a smooth experience that works well in astronomy, download the following plugins from the [https://www.zotero.org/support/plugins list of zotero plugins]: Better BibTex, ZotFile, and optionally the Storage Scanner for Zotero.

=== Zotero configuration ===

To configure zotero, go to Edit->Preferences. The following Image shows my General setup, I have left the other values at their default settings (although you might want to change the data directory location in Advanced->Files and Folders ).

[[File:zotero_1.png||recommended general options for zotero]]

=== ZotFile Configuration ===

Next, configure ZotFiles. This plugin can automatically recognize new PDFs in a Source folder and it can also copy new files to a pdf library that is outside of zotero. This is advantageous since it keeps the zotero storage small such that you can use zotero's online library to move the zotero database around. It also makes your life easier since it is also possible to access PDFs directly if necessary. For ZotFile I use the following settings:

* Source Folder for Attaching New Files: I use '''~/Downloads'''
* Location of Files: Use "Custom Location" and set it to the path where you want to store the PDFs.
* Tick on "User subfolder defined by" and set the field to '''/%y''' . This will sort your media according to the year of publication into subfolders.
* On the tab "Renaming Rules":
** switch off "User Zotero to Rename"
** change "Format for all Item Types except Patents to '''%a_%y_%t''' . This gives filenames consisting of the first author, year of publication, and the abbreviated title of the publication (I find leaving the year in the filename useful in case I need to use the file elsewhere).
** In the additional settings I have '''_''' as the Delimiter between multiple authors and I have ticked "Change to lower case", "Replace blanks", "Truncate title after . or : or ?". Maximum length of title 30 (you might want to shorten this!), maximum number of authors at 1, and I switch off "Add suffix when authors are omitted".

* On the tab "Advanced Settings" I set:
** Automatically rename new attachments to "Always Rename"
** ask for batch rename for 2 or more attachments
** remove special characters from filename

=== Better BibTex Configuration ===

Better BibTex will automatically generate unique bibtex tags. It also contains code to output bib-files from zotero libraries and to keep these updated whenever a new item is added to a library.

In the Better BibTeX configuration, I suggest the following:

* Citation keys:
** Citation key formula: I suggest ```auth.fold.lower+year'''. This generates citation keys consisting of the first author name and a year (postfixed with a, b, c etc. if there are multiple media from the same author in the year. I recommend using lower case names only for simplicity.
** Switch on "Force citation key to plan text"
** I do not use enable citation key search.
** Set Automatically pin citation key after 0 seconds (this ensures that citation keys are fully under control of the plugin)

* Export:
** BibTeX tab:
***switch on "Export unicode as plain-text latex commands"
*** all other check boxes are off.
*** add urls to bibtex export: "in the url field"
** BibLaTex:
*** I recommend not using BibLaTeX. This is a bit unfortunate, since BibLaTeX is a good idea in principle, but it does not scale to larger libraries and it cannot produce reference lists in the way needed by journals in astronomy and astrophysics.
** Fields:
*** export language as langid
*** when an item has both a DOI and a URL, export both
*** fields to omit from export: ```abstract,file,urldate,keywords,issn,language,url,shorttitle,copyright''' (although you might want to leave the url in the bibtex)
*** Include JabRef-specific metadata: no
** Quick-Copy:
*** I do not use this, so I left things at their default values
** postscript
*** This is javascript code that is used to manipulate the generated bibfile. The following code will generate journal fields with LaTeX-commands appropriate for astrophysical journal styles.

<pre>
if (Translator.BetterBibTeX) {
if (reference.has.journal) {
switch(item.publicationTitle) {
case "Acta Astronomica":
reference.add({name: 'journal', value: "\\actaa", enc: 'raw'});
break;
case "Advances in Space Research":
reference.add({name: 'journal', value: "Adv.\ Space Res.", enc: 'raw'});
break;
case "The Astronomical Journal":
reference.add({name: 'journal', value: "\\aj", enc: 'raw'});
break;
case "Annual Review of Astronomy and Astrophysics":
reference.add({name: 'journal', value: "\\araa", enc: 'raw'});
break;
case "Astrophysical Letters and Communications":
reference.add({name: 'journal', value: "\\aplett", enc: 'raw'});
break;
case "Astrophysical Journal":
case "The Astrophysical Journal":
case "The Astrophysical Journal Letters":
case "The Astrophysical Journal, Letters":
reference.add({name: 'journal', value: "\\apj", enc: 'raw'});
break;
case "The Astrophysical Journal Supplement Series":
case "The Astrophysical Journal, Supplement":
reference.add({name: 'journal', value: "\\apjs", enc: 'raw'});
break;
case "Applied Optics":
reference.add({name: 'journal', value: "\\ao", enc: 'raw'});
break;
case "Astrophysics Letters":
reference.add({name: 'journal', value: "\\aplett", enc: 'raw'});
break;
case "Astrophysics and Space Physics Research":
reference.add({name: 'journal', value: "\\apspr", enc: 'raw'});
break;
case "Astrophysics and Space Science":
reference.add({name: 'journal', value: "\\apss", enc: 'raw'});
break;
case "Astronomy and Astrophysics":
case "Astronomy & Astrophysics":
reference.add({name: 'journal', value: "\\aap", enc: 'raw'});
break;
case "Astronomy & Astrophysics Reviews":
case "The Astronomy & Astrophysics Reviews":
reference.add({name: 'journal', value: "\\aapr", enc: 'raw'});
break;
case "Astronomy & Astrophysics Supplement":
case "Astronomy and Astrophysics Supplement Series":
reference.add({name: 'journal', value: "\\aaps", enc: 'raw'});
break;
case "Astronomicheskii Zhurnal":
reference.add({name: 'journal', value: "\\azh", enc: 'raw'});
break;
case "Bulletin of the AAS":
reference.add({name: 'journal', value: "\\baas", enc: 'raw'});
break;
case "Bulletin of the Astronomical Institutes of Czechoslovakia":
reference.add({name: 'journal', value: "\\bac", enc: 'raw'});
break;
case "Bulletin of the Astronomical Institute of the Netherlands":
reference.add({name: 'journal', value: "\\bain", enc: 'raw'});
break;
case "Chinese Astronomy and Astrophysics":
reference.add({name: 'journal', value: "\\caa", enc: 'raw'});
break;
case "Chinese Journal of Astronomy and Astrophysics":
reference.add({name: 'journal', value: "\\cjaa", enc: 'raw'});
break;
case "Fundamental Cosmic Physics":
reference.add({name: 'journal', value: "\\fcp", enc: 'raw'});
break;
case "Geochimica Cosmochimica Acta":
reference.add({name: 'journal', value: "\\gca", enc: 'raw'});
break;
case "Geophysics Research Letters":
reference.add({name: 'journal', value: "\\grl", enc: 'raw'});
break;
case "IAU Circular":
reference.add({name: 'journal', value: "\\iaucirc", enc: 'raw'});
break;
case "Icarus":
reference.add({name: 'journal', value: "\\icarus", enc: 'raw'});
break;
case "Journal of Cosmology and Astroparticle Physics":
reference.add({name: 'journal', value: "\\jcap", enc: 'raw'});
break;
case "Journal of Chemical Physics":
reference.add({name: 'journal', value: "\\jcp", enc: 'raw'});
break;
case "Journal of Geophysics Research":
reference.add({name: 'journal', value: "\\jgr", enc: 'raw'});
break;
case "Journal of Low Temperature Physics":
case "J Low Temp Phys":
reference.add({name: 'journal', value: "J.\\ Low Temp.\\ Phys.", enc: 'raw'});
break;
case "Journal of Quantitative Spectroscopy and Radiative Transfer":
reference.add({name: 'journal', value: "\\jsqrt", enc: 'raw'});
break;
case "Journal of the Royal Astronomical Society of Canada":
reference.add({name: 'journal', value: "\\jrasc", enc: 'raw'});
break;
case "Memoirs of the Royal Astronomical Society":
reference.add({name: 'journal', value: "\\memras", enc: 'raw'});
break;
case "Monthly Notices of the Royal Astronomical Society":
reference.add({name: 'journal', value: "\\mnras", enc: 'raw'});
break;
case "Monthly Notices of the Royal Astronomical Society: Letters":
reference.add({name: 'journal', value: "\\mnras", enc: 'raw'});
break;
case "Memorie Societa Astronomica Italiana":
reference.add({name: 'journal', value: "\\memsai", enc: 'raw'});
break;
case "New Astronomy":
reference.add({name: 'journal', value: "\\na", enc: 'raw'});
break;
case "Nuclear Physics A":
reference.add({name: 'journal', value: "\\nphysa", enc: 'raw'});
break;
case "Physical Review A":
reference.add({name: 'journal', value: "\\pra", enc: 'raw'});
break;
case "Physical Review B":
reference.add({name: 'journal', value: "\\prb", enc: 'raw'});
break;
case "Physical Review C":
reference.add({name: 'journal', value: "\\prc", enc: 'raw'});
break;
case "Physical Review D":
reference.add({name: 'journal', value: "\\prd", enc: 'raw'});
break;
case "Physical Review E":
reference.add({name: 'journal', value: "\\pre", enc: 'raw'});
break;
case "Physical Review Letters":
reference.add({name: 'journal', value: "\\prl", enc: 'raw'});
break;
case "Publications of the Astronomical Society of the Pacific":
reference.add({name: 'journal', value: "\\pasp", enc: 'raw'});
break;
case "Publications of the Astronomical Society of Japan":
reference.add({name: 'journal', value: "\\pasj", enc: 'raw'});
break;
case "Publications of the Astronomical Society of Australia":
reference.add({name: 'journal', value: "\\pasa", enc: 'raw'});
break;
case "Physics Reports":
reference.add({name: 'journal', value: "\\physrep", enc: 'raw'});
break;
case "Physica Scripta":
reference.add({name: 'journal', value: "\\physscr", enc: 'raw'});
break;
case "Planetary Space Science":
reference.add({name: 'journal', value: "\\planss", enc: 'raw'});
break;
case "Proceedings of the SPIE":
reference.add({name: 'journal', value: "\\procspie", enc: 'raw'});
break;
case "Quarterly Journal of the Royal Astronomical Society":
reference.add({name: 'journal', value: "\\qjras", enc: 'raw'});
break;
case "Revista Mexicana de Astronomia y Astrofisica":
reference.add({name: 'journal', value: "\\rmxaa", enc: 'raw'});
break;
case "Sky and Telescope":
reference.add({name: 'journal', value: "\\skytel", enc: 'raw'});
break;
case "Solar Physics":
reference.add({name: 'journal', value: "\\solphys", enc: 'raw'});
break;
case "Soviet Astronomy":
reference.add({name: 'journal', value: "\\sovast", enc: 'raw'});
break;
case "Space Science Reviews":
reference.add({name: 'journal', value: "\\ssr", enc: 'raw'});
break;
case "Zeitschrift für Astrophysik":
reference.add({name: 'journal', value: "\\zap", enc: 'raw'});
break;
}
}
}
</pre>

(NB you can also set individual journal abbreviations in the entries for individual articles; this is recommended for journals not in the above list)

* Tab list continued
**Miscellaneous
*** switch off "automatically abbreviate journal title" and "include comments about potential problems"
*** turn on "include automatic tags in export"
*** when converting to plan text latex: "Minimize the number of switches between math-mode and text-mode"
*** switch on apply title-casing to titles
*** switch on apply case-protection to capitalized words by enclosing them in braces"

* Automatic export: set "on change" to no - this will keep your bibfiles updated

== General recommendations for zotero ==

These are a few additional comments on how I use zotero:

* When writing a paper I generate a new library and copy the references there. This is mainly because my zotero library is very large (more than 6000 individual papers). In most cases, keep things that belong together in the same library (e.g., all neutron star papers in a "neutron star" library, all AGN papers in an "AGN" library).

* Use sublibraries to structure things (e.g., I have libraries for individual sources)

* papers can be in multiple libraries (so if a paper is, e.g., on accretion in a specific source but also contains interesting thoughts about accretion in general, it will be in both, the "accretion library" and the source specific library.

* keep bibfiles in sync for those libraries pertinent to a project you're working on. You do this by pressing the right mouse button and export the collection using "Better Bibtex". Enable "use journal abbreviation", "keep updated", and "background export". Do NOT enable "Export notes" and "Export Files".

* SPIE papers are not exported correctly from the ADS. Go to the journal page at SPIE and get the PDF from there. You might want to check that the editors and conference are set correctly. If not, add them by hand (add a new author and then switch from "Author" to "Editor".

Jupyter Notebook for ISIS/Slang

2023-06-28T13:11:40Z

Wilms: /* Embedding images */

If you want to start an ISIS session with a jupyter notebook this should be straight forward on the cluster. For this you need to load two modules via the module system
<pre>
module load conda slang-jupyter
</pre>
Once this is done you need to access the conda environment via
<pre>
conda activate
</pre>
Here you can start the jupyter server, but make sure that the shell where you start the server has all needed modules loaded (e.g., if you need localmodels, for example tbnew, make sure it is activated. If you never actively loaded a module to use ISIS, you are probably good).

Start the server
<pre>
jupyter notebook
</pre>
now you should be greeted with the usual page from the notebooks where you can open notebooks etc. The folder were you started the server is the root folder and you can not go above this level. If you want to start a ISIS notebook, just create a new notebook and select ''isis'' (there is also a ''slang'' kernel, that is not the same!). Having the notebook opened you should be able to run commands in the cells as usual. The notebook acts as one document, so functions and variables defined in one cell are accessible in another (provided the cell with the definitions was executed first). For details about the notebook interactions check the manual of jupyter itself.

== Embedding images ==

Currently the kernel (that is the part of the software that translates your input to isis) has no built in feature to display images. If you issue a ''plot'' command and you are locally at the machine a normal pgplot will open just as it is with the ''isis'' shell. The simplest way to include an image in the notebook is to plot into a png file
<pre>
variable pg = open_plot("my-cool-plot.png/png"); % this opens a plot to a png file, any plot command afterwards will draw to this file
xlabel("X-axis");
ylabel("Y-axis");
plot([0:4:#100], sin([0:4:#100]));
oplot([0,4], [0,1]);
close_plot(pg); % this is important, if you don't close the file, any additional plot command will create a new file with appended counter
</pre>

The created png can be included in the notebook with a markdown cell
<pre>
![Example Text](my-cool-plot.png)
</pre>
where the text in square brackets is the description, this can be left empty (but the brackets are necessary).

This way you can also use xfig or tikz to create pdfs or png and embed them accordingly.

== Remote Access ==

If you want to work on a notebook remotely then this is not directly possible for various reasons but mainly because this would allow everyone to execute arbitrary code on our cluster (and, in case this was not clear, we don't want that).
There is, however, a way to forward the server via an ssh tunnel between your computer (let's say you use a laptop) and the cluster.

To do so, you first have to get the information about where the server is running
<pre>
jupyter notebook list # make sure the conda environment is activated to have access to jupyter
</pre>
This will show you a line similar to
<pre>
http://localhost:8888/?token=2b9af3b8973be0b3270d0cf93941969db373bd70bfe195ea :: /home/stierhof
</pre>
where the first part is the address where the server is accessible (locally) and the second is the root folder where it is running.
Now to access the server '''on your laptop''', create the tunnel with
<pre>
ssh -NL 8888:localhost:8888
</pre>
This command will not return and seemingly do nothing! You need to keep the shell where you started the tunnel open, if you close it the tunnel will be closed too.
In this example the number 8888 is the port number from the listed notebook above, if you are shown a different number you also have to change it in the ''ssh'' command (but 8888 is the default port).
Once the ssh tunnel connects you local port with the port on the cluster you can paste the full address as shown by the ''jupyter notebook list'' command into a browser and access the server from there in the usual way.

== Disclaimer ==

The software that enables isis to be used in a jupyter notebook is not very well tested yet. If you find any problems, or better yet, have solutions to problems or ideas for features, please let me know - [mailto:jakob.stierhof@fau.de Jakob Stierhof]

[[Category:Software]]

Remeis English Checklist

2023-06-14T09:18:28Z

Wilms: /* Spelling and Word usage */

====== The Remeis English Checklist ======

(by J. Wilms and K. Pottschmidt)

'''''First of all and most importantly:'''''

* did you read the instructions to authors of the journal? If you are working on a thesis, did you read those of [http://www.aanda.org/doc_journal/instructions/aadoc.pdf Astronomy and Astrophysics]?
* did you read appendix A of the [https://journals.aps.org/files/rmpguide.pdf instructions to authors] of Rev Mod Phys?

==== Punctuation ====

* did you remove all commas before "that"?
* did you end your footnotes and captions with a full stop (".")?
* did you make sure that your use of "data" is correct and uses plural verbs?
* did you make sure that you do not have a ":" anywhere before an equation, but that your equations are seen as part of your sentences?
* did you make sure that you have commas surrounding "i.e." and "e.g."?

==== Spelling and Word usage ====

* do you consistently use either British or American spelling?
* did you run a spell checker over your manuscript? For TeX, use "ispell" or the built in spell checker in emacs.
* did you make sure not to use country prefixes in addresses in the author list?
* did you avoid passive voice as much as possible?
* did you make sure that you are //not// using "The found results are..." and similar German constructs in your text?
* did you make sure that everything in your text that is not your original result is accompanied by proper citations?
* did you make sure that you distinguish between "estimate" and "estimation" by replacing all "estimation" with "estimate"?
* did you replace all uses of "exemplary" by "example"?
* did you use "short" for length intervals and "brief" for time intervals? (but note that "short of duration" is correct)
* did you replace all uses of "the actual value" by "the real value"? (if you are German, "actual" does not mean "aktuell"!)
* did you remove all uses of "hence" and "thereby"?
* did you make sure that you use "however" as sparingly as possible?
* did you make sure that you did not use "the equation reads..", but rather used "the equation is..." or "the equation is given by..."?
* did you avoid split infinitives? ("to boldly go..." is wrong; yes, in many cases split infinitives are ok in current English, but they tend to be so often used wrongly by non-native speakers that it is best to avoid them)
* did you make sure that you distinguish properly between "this" and "these"?
* did you make use of the "Oxford comma", i.e., do you have a comma before "and" in lists?
* did you use "i.e." and "e.g." correctly, i.e., using "i.e." for a specific clarification or definition and "e.g." where you would otherwise use "for example"?
* did you use the IAU recommended year - month - day sequences (2016 March 15)?
* did you make sure that you did not use contractions such as "didn't" or "you're"?
* did you replace "cf." with "see" everywhere since you know that "cf." means "compare"?
* did you ensure that you use "opportunity" where in German you would be using "Chance" or "Gelegenheit" (and did not use "chance"...)?
* did you make sure that the reader will understand what thing you refer to when using "it" rather than naming it?
* did you make sure that all uses of "this" are followed by the object you are referring to?
* did you use "led" rather than "lead" when using the past tense of the verb "to lead"?
* did you reread the manuscript for internal consistency after you added comments from your coauthors?
* did you make sure that your sentences are short (rule of thumb: if a sentence goes over more than three lines it is probably too long)?
* did you check that you did not combine two sentences that could be separate sentences with "and"?
* did you avoid abbreviations as much as possible and only used them when they are really, really common (HST, AGN, XMM,...)?
* did you check that you defined all abbreviations that you used at their first usage? ("...Active Galactic Nucleus (AGN)..." //not// "...AGN (Active Galactic Nucleus)..." )

==== Citations ====

* did you add the journal to all publications where you list the arXiv-reference and not just blindly copy the erroneous ADS bibtex entry?
* did you make sure that you distinguished between arXiv references where a paper is submitted and references where a paper is already accepted by checking the paper author's comment on the arXiv-page for that article?
* did you remove the page number for all ATEL-references downloaded from ADS and changed the journal name to "Astron. Tel." or "ATEL"? (and similar for IAU telegrams)
* did you add editors and the title of the conference publication to all conference publications?
* did you add the publisher and place information (city only) to all books, conference publications, and other book-like publications that you are citing?
* did you check that your references are correct in that you are using ''\citet{biblabel}'' for references in the text and ''\citep{biblabel}'' for references in parentheses?
* did you make sure that none of your ''\citet{..}'' commands refer to more than one biblabel?

==== Typesetting (mainly in TeX) ====

* did you check for missing spaces between values and units?
* did you make sure that all scientific units are typeset in <code>\mathrm</code>?
* did you make sure not to use constructs such as <code>$\mathrm{m}/\mathrm{s}$</code> by using <code>$\mathrm{m}\,\mathrm{s}^{-1}$</code> instead?
* did you make sure that almost all of your error bars are rounded up to only one significant digit rather than following the DIN-norm (which is not applied in astronomical journals)?
* did you make sure that you are not using any positioning commands for the table or figure environment such as <code>\begin{table}[htpb]</code>?
* did you make sure that your tables have captions above the table, and figures have captions below the figure or next to it (where allowed by the style)?
* did you make sure that you use empty lines to denote the start of a new paragraph rather than the ''\\''-command? (use <code>\parindent{0pt}</code> if you do not want to indent paragraphs)
* did you make sure that there are no paragraph endings above or below <code>\begin{equation}...\end{equation}</code> by ensuring that there is no empty line above or below the ''equation''-environment?
* did you make sure that you are not using <code>$\frac{a}{b}$</code> in normal text, but use <code>$a/b$</code> instead?
* did you make sure that you are not using the <code>displaymath</code>-environment and that all equations are numbered?
* did you make sure that all of your sections, subsections, paragraphs and so on are numbered?
* did you avoid any and all uses of <code>\bf</code>, <code>\it</code>, <code>\sl</code>, or <code>\em</code> and use the proper commands <code>\textbf</code>, <code>\textit</code>, <code>\textsl</code>, and <code>\emph</code> instead?
* did you use the en-dash of TeX for ranges, even if they occur in math, by using <code>--</code> in text mode rather than a minus sign? (that is, did you typeset a range in an equation as <code>$3x$--$5x$</code> or <code>$3x\mbox{--}5x$</code> rather than, erroneously, <code>$3x-5x$</code>?
* did you correctly use the minus-sign and dashes in astronomical source names, where the name contains coordinates and the <q>dash</q> really is a southern declination or Galactic latitude, that is, did you typeset <code>Her X-1</code>, <code>LMC X-3</code>, but <code>GX\,339$-$4</code> or <code>IGR J16318$-$4848</code> (and as a really difficult one: <code>MCG$-$6-30-15</code>)?
* did you make sure to typeset hydrogen equivalent columns as <code>$N_\mathrm{H}$</code> rather than $n_H$ or $n_\mathrm{H}$? (note: in astronomy, $n$ denotes a particle density, so it has units of particles per cubic centimeter, while N is a column with units of particles per square centimeter; a certain analysis program uses nH for this parameter, but this does not mean that n should be used in papers).

[[Category:Current Members]]

Remeis English Checklist

2022-09-06T23:26:09Z

Wilms: /* Typesetting (mainly in TeX) */

====== The Remeis English Checklist ======

(by J. Wilms and K. Pottschmidt)

'''''First of all and most importantly:'''''

* did you read the instructions to authors of the journal? If you are working on a thesis, did you read those of [http://www.aanda.org/doc_journal/instructions/aadoc.pdf Astronomy and Astrophysics]?
* did you read appendix A of the [https://journals.aps.org/files/rmpguide.pdf instructions to authors] of Rev Mod Phys?

==== Punctuation ====

* did you remove all commas before "that"?
* did you end your footnotes and captions with a full stop (".")?
* did you make sure that your use of "data" is correct and uses plural verbs?
* did you make sure that you do not have a ":" anywhere before an equation, but that your equations are seen as part of your sentences?
* did you make sure that you have commas surrounding "i.e." and "e.g."?

==== Spelling and Word usage ====

* do you consistently use either British or American spelling?
* did you run a spell checker over your manuscript? For TeX, use "ispell" or the built in spell checker in emacs.
* did you make sure not to use country prefixes in addresses in the author list?
* did you avoid passive voice as much as possible?
* did you make sure that you are //not// using "The found results are..." and similar German constructs in your text?
* did you make sure that everything in your text that is not your original result is accompanied by proper citations?
* did you make sure that you distinguish between "estimate" and "estimation" by replacing all "estimation" with "estimate"?
* did you replace all uses of "exemplary" by "example"?
* did you use "short" for length intervals and "brief" for time intervals? (but note that "short of duration" is correct)
* did you replace all uses of "the actual value" by "the real value"? (if you are German, "actual" does not mean "aktuell"!)
* did you remove all uses of "hence" and "thereby"?
* did you make sure that you use "however" as sparingly as possible?
* did you make sure that you did not use "the equation reads..", but rather used "the equation is..." or "the equation is given by..."?
* did you avoid split infinitives? ("to boldly go..." is wrong; yes, in many cases split infinitives are ok in current English, but they tend to be so often used wrongly by non-native speakers that it is best to avoid them)
* did you make sure that you distinguish properly between "this" and "these"?
* did you make use of the "Oxford comma", i.e., do you have a comma before "and" in lists?
* did you use "i.e." and "e.g." correctly, i.e., using "i.e." for a specific clarification or definition and "e.g." where you would otherwise use "for example"?
* did you use the IAU recommended year - month - day sequences (2016 March 15)?
* did you make sure that you did not use contractions such as "didn't" or "you're"?
* did you replace "cf." with "see" everywhere since you know that "cf." means "compare"?
* did you make sure that the reader will understand what thing you refer to when using "it" rather than naming it?
* did you make sure that all uses of "this" are followed by the object you are referring to?
* did you use "led" rather than "lead" when using the past tense of the verb "to lead"?
* did you reread the manuscript for internal consistency after you added comments from your coauthors?
* did you make sure that your sentences are short (rule of thumb: if a sentence goes over more than three lines it is probably too long)?
* did you check that you did not combine two sentences that could be separate sentences with "and"?
* did you avoid abbreviations as much as possible and only used them when they are really, really common (HST, AGN, XMM,...)?
* did you check that you defined all abbreviations that you used at their first usage? ("...Active Galactic Nucleus (AGN)..." //not// "...AGN (Active Galactic Nucleus)..." )

==== Citations ====

* did you add the journal to all publications where you list the arXiv-reference and not just blindly copy the erroneous ADS bibtex entry?
* did you make sure that you distinguished between arXiv references where a paper is submitted and references where a paper is already accepted by checking the paper author's comment on the arXiv-page for that article?
* did you remove the page number for all ATEL-references downloaded from ADS and changed the journal name to "Astron. Tel." or "ATEL"? (and similar for IAU telegrams)
* did you add editors and the title of the conference publication to all conference publications?
* did you add the publisher and place information (city only) to all books, conference publications, and other book-like publications that you are citing?
* did you check that your references are correct in that you are using ''\citet{biblabel}'' for references in the text and ''\citep{biblabel}'' for references in parentheses?
* did you make sure that none of your ''\citet{..}'' commands refer to more than one biblabel?

==== Typesetting (mainly in TeX) ====

* did you check for missing spaces between values and units?
* did you make sure that all scientific units are typeset in <code>\mathrm</code>?
* did you make sure not to use constructs such as <code>$\mathrm{m}/\mathrm{s}$</code> by using <code>$\mathrm{m}\,\mathrm{s}^{-1}$</code> instead?
* did you make sure that almost all of your error bars are rounded up to only one significant digit rather than following the DIN-norm (which is not applied in astronomical journals)?
* did you make sure that you are not using any positioning commands for the table or figure environment such as <code>\begin{table}[htpb]</code>?
* did you make sure that your tables have captions above the table, and figures have captions below the figure or next to it (where allowed by the style)?
* did you make sure that you use empty lines to denote the start of a new paragraph rather than the ''\\''-command? (use <code>\parindent{0pt}</code> if you do not want to indent paragraphs)
* did you make sure that there are no paragraph endings above or below <code>\begin{equation}...\end{equation}</code> by ensuring that there is no empty line above or below the ''equation''-environment?
* did you make sure that you are not using <code>$\frac{a}{b}$</code> in normal text, but use <code>$a/b$</code> instead?
* did you make sure that you are not using the <code>displaymath</code>-environment and that all equations are numbered?
* did you make sure that all of your sections, subsections, paragraphs and so on are numbered?
* did you avoid any and all uses of <code>\bf</code>, <code>\it</code>, <code>\sl</code>, or <code>\em</code> and use the proper commands <code>\textbf</code>, <code>\textit</code>, <code>\textsl</code>, and <code>\emph</code> instead?
* did you use the en-dash of TeX for ranges, even if they occur in math, by using <code>--</code> in text mode rather than a minus sign? (that is, did you typeset a range in an equation as <code>$3x$--$5x$</code> or <code>$3x\mbox{--}5x$</code> rather than, erroneously, <code>$3x-5x$</code>?
* did you correctly use the minus-sign and dashes in astronomical source names, where the name contains coordinates and the <q>dash</q> really is a southern declination or Galactic latitude, that is, did you typeset <code>Her X-1</code>, <code>LMC X-3</code>, but <code>GX\,339$-$4</code> or <code>IGR J16318$-$4848</code> (and as a really difficult one: <code>MCG$-$6-30-15</code>)?
* did you make sure to typeset hydrogen equivalent columns as <code>$N_\mathrm{H}$</code> rather than $n_H$ or $n_\mathrm{H}$? (note: in astronomy, $n$ denotes a particle density, so it has units of particles per cubic centimeter, while N is a column with units of particles per square centimeter; a certain analysis program uses nH for this parameter, but this does not mean that n should be used in papers).

[[Category:Current Members]]

Slurm

2020-12-04T09:19:17Z

Wilms: /* Submitting a job array where each command needs to change into a different directory */

[[Category:Slurm]]

= About =

In order to spread the workload of scientific computations on our compute nodes the resource manager SLURM is used.

From [https://slurm.schedmd.com/overview.html official SLURM website]:

''Slurm is an open source, fault-tolerant, and highly scalable cluster management and job scheduling system for large and small Linux clusters. Slurm requires no kernel modifications for its operation and is relatively self-contained. As a cluster workload manager, Slurm has three key functions. First, it allocates exclusive and/or non-exclusive access to resources (compute nodes) to users for some duration of time so they can perform work. Second, it provides a framework for starting, executing, and monitoring work (normally a parallel job) on the set of allocated nodes. Finally, it arbitrates contention for resources by managing a queue of pending work.''
[[File:entities_slurm.gif|frame|Different entities of Slurm]]
From [https://slurm.schedmd.com/overview.html official SLURM website]:

''SLURM manages the cluster in partitions, which are a set of compute nodes. Note, that partitions may overlap, e.g. one compute node may be in two or more partitions. A node is a physical computer which provides consumable resources: CPUs and Memory. A CPU does not necessarily have to be a physical processor but is more like a virtual CPU to run one single task on. A dual core with hyper threading technology, for instance, would show up as a node with 4 CPUs consisting of two cores with the capability of running two threads on each core. Physical memory is defined in MB.''

The following partitions exist in the current setup:

* remeis: default partition, all machines, timelimit: 7days
* erosita: only available for selected people involved in the project, timelimit: infinite
* debug: very high priority partition for software development, timelimit: 1h

= Quick users tutorial =

This tutorial will give you a quick overview over the most important commands. The [https://slurm.schedmd.com/overview.html official SLURM website] provides more detailed information.

== Get cluster status ==
In order to get an overview of the cluster, type
<pre>
sinfo
</pre>
This command offers a variety of options how to format the output. In order to get a detailed output while focusing on the nodes rather than the partitions, type
<pre>
sinfo -N -l
</pre>
An overview over the available partitions can be shown with
<pre>
scontrol show partition
</pre>
an the current queued and running jobs can be displayed using
<pre>
squeue
</pre>

== Executing a job in real-time ==
In order to allocate for instance 1 CPUs and 100MB of memory for real-time work, type
<pre>
salloc --mem-per-cpu=100 -n1 bash
</pre>
Your bash is now connected to the compute nodes. In order to execute a script use the srun-command
<pre>
srun my_script.sh
</pre>
Each srun-command you execute now is interpreted as a job step. The currently running job step of submitted jobs can be displayed using
<pre>
squeue -s
</pre>

You can also start a job by simply use the srun command and specify your requirements. In the following case, srun will allocate 100MB of memory and 1 CPU(s) for 1 task, only for the duration of execution.
<pre>
srun --mem-per-cpu=100 -n1 my_script.sh
</pre>
If resources are available your job will start immediately.

== Submitting a job for later execution ==

The most convenient way is to submit a job script for later execution. The top part of the script contains scheduling information for SLURM, the more information you provide here, the better.

First of all, a job name is specified, followed by a maximum time. If your job exceeds this time, it will be killed. However, do not overestimate too much because short jobs might start earlier. Acceptable time formats include "minutes", "minutes:seconds", "hours:minutes:seconds", "days-hours", "days-hours:minutes" and "days-hours:minutes:seconds". The output file is set to be test-job(jobID).out and the partition to run the job on is "remeis".
The sbatch-script itself will not initiate any job but only allocate the resources. The ''ntasks'' and ''mem-per-cpu'' options advise the SLURM controller that job steps run within the allocation will launch a maximum of number tasks and to provide for sufficient resources.

The ''srun'' commands in the job script launch the job steps. The example below thus consists of two job steps. Each of the ''srun'' commands may have own requirements concerning memory any may also spawn less tasks than given in the header of the script file. However, the values in the header may never be exceeded!
<pre>
#!/bin/bash
#SBATCH --job-name my_first_job
#SBATCH --time 05:00
#SBATCH --output test-job_%A_%a.out
#SBATCH --error test-job_%A_%a.err
#SBATCH --partition=remeis
#SBATCH --ntasks=4
#SBATCH --mem-per-cpu=100
srun -l my_script1.sh
srun -l my_script2.sh
</pre>
The ''-l'' parameter of ''srun'' will print the task number in front of a line of stdout/err. You can submit this script by saving it in a file, e.g. ''my_first_job.slurm'', and sumitting it using
<pre>
cepheus:~> sbatch my_first_job.slurm
Submitted batch job 144
</pre>

You can check the estimated starting time of your job using
<pre>
squeue --start
</pre>

== Submitting a job array ==

In order to submit a array of jobs with the same requirements you have to modify your script file.
The script above is going to spawn 4 jobs each consisting of one srun command. Note the presence of the new environment variable ''${SLURM_ARRAY_TASK_ID}'' which might be useful for your work. In this example we start an isis-script with different input values. You can also simply use different scripts.
<pre>
#!/bin/bash
#SBATCH --partition remeis
#SBATCH --job-name important_job
#SBATCH --ntasks=1
#SBATCH --time 00:05:00
#SBATCH --output /home/dauser/tmp/jobscript_beta.%A_%a.out
#SBATCH --error /home/dauser/tmp/jobscript_beta.%A_%a.err
#SBATCH --array 0-3

cd /home/user/script/

COMMAND[0]="./sim_script.sl 0.00"
COMMAND[1]="./sim_script.sl 0.10"
COMMAND[2]="./sim_script.sl 0.20"
COMMAND[3]="./sim_script.sl 0.30"

srun /usr/bin/nice -n +19 ${COMMAND[$SLURM_ARRAY_TASK_ID]}
</pre>
Note that it is often much better not to hard code the parameters of your job in the batch script, but to move that logic into the simulation script:
<pre>
#!/bin/bash
#SBATCH --partition remeis
#SBATCH --job-name important_job
#SBATCH --ntasks=1
#SBATCH --time 00:05:00
#SBATCH --output /home/dauser/tmp/jobscript_beta.%A_%a.out
#SBATCH --error /home/dauser/tmp/jobscript_beta.%A_%a.err
#SBATCH --array 0-3

cd /home/user/script/
srun /usr/bin/nice -n +19 ./script --param=${SLURM_ARRAY_TASK_ID}
</pre>
In this case, the script will use the command line parameter param to identify what is to be done (all programming languages have ways to access command line parameters, for isis, you might want to take a look at the cmdopt tool, for perl use Getopt::Long, for C use getopt or getopt_long in the Gnu C library, for python use the argparse module).

As above, this code might be saved in a file, for example ''job.slurm'' can be executed using
<pre>
sbatch job.slurm
</pre>

If you need a specific machine to run your job on, you can use
<pre>
#SBATCH --nodelist=leo,draco
</pre>
If you have a job with high I/O and/or traffic on the network you can limit the number of jobs running simultaneously (to 2 in this example) by
<pre>
#SBATCH --array 0-3%2
</pre>
SLURM will only allocate resources on the given nodes. However, if all nodes in 'nodelist' cannot fulfill the job requirements, SLURM will also allocate other machines.

If you would like to cancel jobs 1, 2 and 3 from job array 20 use
<pre>
scancel 20_[1-3]
</pre>
Note that you might have to escape the brackets when using the above command, e.g.,
<pre>
tcsh:~> scancel 20_\[1-3\]
</pre>
If you want to cancel the whole array, ''scancel'' works as usual
<pre>
scancel 20
</pre>
Note, there is also the option to modify requirements of single jobs later using ''scontrol update job=101_1 ...''.

If you have jobs which are dependent on the result of others or if you want a more detailed description concerning job arrays you can find it in the official SLURM manual: [[https://slurm.schedmd.com/job_array.html]]

== Submitting a job array where each command needs to change into a different directory ==

In order to allow each command of the job array to change into an individual directory (as opposed to all into the same directory as above), modify the script as follows:
<pre>
#!/bin/bash
#SBATCH --partition remeis
#SBATCH --job-name important_job
#SBATCH --ntasks=1
#SBATCH --time 00:05:00
#SBATCH --output /home/dauser/tmp/jobscript_beta.%A_%a.out
#SBATCH --error /home/dauser/tmp/jobscript_beta.%A_%a.err
#SBATCH --array 0-3

DIR[0]="/home/user/dir1"
DIR[1]="/home/user/dir2"
DIR[2]="/userdata/user/dir3"
DIR[3]="/userdata/user/dir4"

cd ${DIR[$SLURM_ARRAY_TASK_ID]}

COMMAND[0]="./sim_script.sl 0.00"
COMMAND[1]="./sim_script.sl 0.10"
COMMAND[2]="./sim_script.sl 0.20"
COMMAND[3]="./sim_script.sl 0.30"

srun /usr/bin/nice -n +19 ${COMMAND[$SLURM_ARRAY_TASK_ID]}
</pre>
This also works with paths relative to the directory where the slurm script was submitted.

As also discussed above, as an alternative you might want to move the logic concerning the working directories and parameters into your script.

== Submitting a job array with varying number of tasks ==

This is not really a job "array". But to execute multiple jobs with different number of tasks one can use multiple
srun calls chained with an '&'. This will submit the jobs at once but allow one to specify job parameters individually
for each job.

Example: Simultaneous fit of multiple datasets with different functions

<syntaxhighlight lang="bash" line='line'>
#!/bin/bash
#SBATCH --job-name my_simultaneous_fit_%n
#SBATCH --time 05:00
#SBATCH --output test-job_%A_%a.out
#SBATCH --error test-job_%A_%a.err
#SBATCH --partition=remeis
#SBATCH --mem-per-cpu=100
srun -l my_complicated_fit.sh 2 --ntasks=2 & # my_complicated_fit fits 2 line centers -> needs 2 tasks
srun -l my_complicated_fit.sh 4 --ntasks=4 # my_complicated_fit fits 4 line centers -> needs 4 tasks
</syntaxhighlight>

== Graphical jobs (srun.x11) ==
Not all applications run only on the commandline. Slurm does not support graphical applications natively but there is a wrapper script available which allocates the resources on the cluster and then provides a [[screen]] session inside a running [[SSH|SSH-session]] to the host where the resources have been allocated on. For example
<pre>
[12:06]weber@lynx:~$ srun.x11
</pre>
results in a new shell :
<pre>
[12:06]weber@messier15:~$
</pre>

which forwards the window if you start a graphical program for example
<pre>
[12:06]weber@messier15:~$ kate
</pre>
would open the text editor [[https://de.wikipedia.org/wiki/Kate_(KDE) kate]]. However, this only uses the standard resources set for the remeis partition. If you have other requirements you can also specify these in exactly the same way as for ''srun'':
<pre>
[12:06]weber@lynx:~$ srun.x11 --mem=2G
</pre>
would allocate 2GB of memory for the application.

== Using the ''erosita'' partition (serpens)==

If you are allowed to use the eRosita Partition, contact the admin list. Once your username is added to the list of privileged users, you just have to add
<pre>
#SBATCH --partition=erosita
#SBATCH --account=erosita
</pre>
to your jobfiles.

== Other useful commands ==

* ''sstat'' Real-time status information of your running jobs

* ''sattach <jobid.stepid>'' Attach to stdI/O of one of your running jobs

* ''scancel [OPTIONS...] [job_id[_array_id][.step_id]] [job_id[_array_id][.step_id]...]'' Cancel the execution of one of your job arrays/jobs/job steps.

* ''scontrol'' Administration tool, you can for example use this to modify the requirements of your jobs. You can for exaple show your jobs ''show jobs'' or update the time limit ''update JobId= TimeLimit=2''.

* ''smap'' graphically view information about Slurm jobs, partitions, and set configurations parameters.

* ''sview'' graphical user interface for those who prefer clicking over typing. X-Server required.

= SLURM and MPI =
== About MPI ==
MPI (the Message Passing Interface) makes it possible to run parallel processes on CPUs of different hosts. To do so it uses TCP packets to communicate via the normal network connection. Some tasks can profit a lot of using more cores for computation.
At Remeis MPICH2 is used for initialisation of MPI tasks which is well supported within Slurm. The process manager is called '''pmi2''' and is set as default for srun. If an older MPI process manager is needed, for example for older MPI applications used in '''torque''', it can be set with
<pre>
#SBATCH --mpi=
</pre>
in the submission script.
<pre>
srun --mpi=list
</pre>
provides a list of supported MPI process managers.

The implementation of MPI for SLang/ISIS is called '''SLMPI'''.

== Best practice for MPI tasks ==

The usage of MPI might cause continuously high network traffic especially on the host which holds the master process. Please consider this when deciding which nodes are used for the job. It's a good idea to provide servers (e.g. leo or lupus) with the ''--nodelist='' option one of which is then used to hold the master process since nobody is sitting in front of it and trying to use a browser. Additional nodes are allocated automatically by Slurm if required to fit the ''--ntasks'' / ''-n'' option.

MPI jobs depend on all allocated nodes to be up and running properly, so I'd like to use this opportunity to remind about shutting down/rebooting PCs on your own without any permission can abort a whole MPI job.

== Requirements and Tips ==
To use MPI obviously the application or function used should support MPI. Examples range from programs written in C using some MPI features and compiled with the ''mpicc'' compiler to common ISIS-functions such as ''mpi_emcee'' or ''mpi_fit_pars''.

Keep in mind that everything in the compiled programs/scripts which is not an MPI compatible function is executed on each node on its own. For example in ISIS with ''-n 20'':
<pre>
fit_counts;
</pre>
would fit the defined function to the dataset 20 times at once. That's not very helpful so think about which tasks should be performed in the actual MPI process. Special care has to be taken if something has to be saved as a file. Consider:
<pre>
save_par("test.par");
</pre>
with ''-n 20''. This would save the current fit parameters to '''test.par''' in the working directory 20 times at exactly the same time. This might be helpful if the file is needed on the scratch disk of each node, but doing this on for example ''/userdata'' can cause serious trouble. The function ''mpi_master_only'' can be used to perform a user defined task in an MPI job only once. Best way is to only submit an MPI job to Slurm which only contains actual MPI functions. If some models in ISIS are used which output something to stdout or stderr while loading these messages are also generated 20 times since it's loaded in each process individually.

== Usage ==
If the job is a valid MPI process then the submission works exactly like for any other job:
<pre>
#!/bin/bash
#SBATCH --job-name my_first_mpi_job
#SBATCH ...
#SBATCH --ntasks=20
cd /my/working/dir
srun /usr/bin/nice -n +15 ./my_mpi_script
</pre>
It might be necessary to set a higher memory usage than for the according non MPI job since some applications try to limit the network traffic by just copying the required data to each node in the first place.

Also make sure that if it is necessary to specify the number of child processes in the application itself, set it to the same as with the ''--ntasks'' / ''-n'' option in the submission. An example would be the ''num_slaves'' qualifier in ''mpi_emcee''.

Note that the ''srun'' command does not contain ''mpiexec'' or ''mpirun'' which were used in older versions of MPI to launch the processes. The processes manager ''pmi2'' is built into Slurm and makes it possible that Slurm itself can initialize the network communication with the ''srun'' command only.

Of course it's also possible to run the MPI process directly from the commandline. As an example let's have a look at the calculation of pi with the MPI program ''cpi''. The program comes with the source code of MPICH2 and is compiled in the ''check'' rule. It's located in
<pre>
/data/system/software/mpich/mpich-3.2/examples
</pre>
To run the calculation in 10 parallel processes directly from the commandline use:
<pre>
[1:11]weber@lynx:/data/system/software/mpich/mpich-3.2/examples> srun -n 10 ./cpi
Process 0 of 10 is on aquarius
Process 1 of 10 is on ara
Process 6 of 10 is on asterion
Process 2 of 10 is on ara
Process 8 of 10 is on asterion
Process 7 of 10 is on asterion
Process 3 of 10 is on aranea
Process 5 of 10 is on aranea
Process 4 of 10 is on aranea
Process 9 of 10 is on cancer
pi is approximately 3.1415926544231256, Error is 0.0000000008333325
wall clock time = 0.010601
</pre>
As we can see Slurm launched 10 processes distributed to aquarius, ara, asterion, aranea and cancer. Keep in mind that running MPI interactively doesn't really make sense. The best way to go is to write a submission script like explained above and let Slurm handle the initialisation.

Slurm

2020-12-04T09:17:49Z

Wilms: added text about command line arguments

[[Category:Slurm]]

= About =

In order to spread the workload of scientific computations on our compute nodes the resource manager SLURM is used.

From [https://slurm.schedmd.com/overview.html official SLURM website]:

''Slurm is an open source, fault-tolerant, and highly scalable cluster management and job scheduling system for large and small Linux clusters. Slurm requires no kernel modifications for its operation and is relatively self-contained. As a cluster workload manager, Slurm has three key functions. First, it allocates exclusive and/or non-exclusive access to resources (compute nodes) to users for some duration of time so they can perform work. Second, it provides a framework for starting, executing, and monitoring work (normally a parallel job) on the set of allocated nodes. Finally, it arbitrates contention for resources by managing a queue of pending work.''
[[File:entities_slurm.gif|frame|Different entities of Slurm]]
From [https://slurm.schedmd.com/overview.html official SLURM website]:

''SLURM manages the cluster in partitions, which are a set of compute nodes. Note, that partitions may overlap, e.g. one compute node may be in two or more partitions. A node is a physical computer which provides consumable resources: CPUs and Memory. A CPU does not necessarily have to be a physical processor but is more like a virtual CPU to run one single task on. A dual core with hyper threading technology, for instance, would show up as a node with 4 CPUs consisting of two cores with the capability of running two threads on each core. Physical memory is defined in MB.''

The following partitions exist in the current setup:

* remeis: default partition, all machines, timelimit: 7days
* erosita: only available for selected people involved in the project, timelimit: infinite
* debug: very high priority partition for software development, timelimit: 1h

= Quick users tutorial =

This tutorial will give you a quick overview over the most important commands. The [https://slurm.schedmd.com/overview.html official SLURM website] provides more detailed information.

== Get cluster status ==
In order to get an overview of the cluster, type
<pre>
sinfo
</pre>
This command offers a variety of options how to format the output. In order to get a detailed output while focusing on the nodes rather than the partitions, type
<pre>
sinfo -N -l
</pre>
An overview over the available partitions can be shown with
<pre>
scontrol show partition
</pre>
an the current queued and running jobs can be displayed using
<pre>
squeue
</pre>

== Executing a job in real-time ==
In order to allocate for instance 1 CPUs and 100MB of memory for real-time work, type
<pre>
salloc --mem-per-cpu=100 -n1 bash
</pre>
Your bash is now connected to the compute nodes. In order to execute a script use the srun-command
<pre>
srun my_script.sh
</pre>
Each srun-command you execute now is interpreted as a job step. The currently running job step of submitted jobs can be displayed using
<pre>
squeue -s
</pre>

You can also start a job by simply use the srun command and specify your requirements. In the following case, srun will allocate 100MB of memory and 1 CPU(s) for 1 task, only for the duration of execution.
<pre>
srun --mem-per-cpu=100 -n1 my_script.sh
</pre>
If resources are available your job will start immediately.

== Submitting a job for later execution ==

The most convenient way is to submit a job script for later execution. The top part of the script contains scheduling information for SLURM, the more information you provide here, the better.

First of all, a job name is specified, followed by a maximum time. If your job exceeds this time, it will be killed. However, do not overestimate too much because short jobs might start earlier. Acceptable time formats include "minutes", "minutes:seconds", "hours:minutes:seconds", "days-hours", "days-hours:minutes" and "days-hours:minutes:seconds". The output file is set to be test-job(jobID).out and the partition to run the job on is "remeis".
The sbatch-script itself will not initiate any job but only allocate the resources. The ''ntasks'' and ''mem-per-cpu'' options advise the SLURM controller that job steps run within the allocation will launch a maximum of number tasks and to provide for sufficient resources.

The ''srun'' commands in the job script launch the job steps. The example below thus consists of two job steps. Each of the ''srun'' commands may have own requirements concerning memory any may also spawn less tasks than given in the header of the script file. However, the values in the header may never be exceeded!
<pre>
#!/bin/bash
#SBATCH --job-name my_first_job
#SBATCH --time 05:00
#SBATCH --output test-job_%A_%a.out
#SBATCH --error test-job_%A_%a.err
#SBATCH --partition=remeis
#SBATCH --ntasks=4
#SBATCH --mem-per-cpu=100
srun -l my_script1.sh
srun -l my_script2.sh
</pre>
The ''-l'' parameter of ''srun'' will print the task number in front of a line of stdout/err. You can submit this script by saving it in a file, e.g. ''my_first_job.slurm'', and sumitting it using
<pre>
cepheus:~> sbatch my_first_job.slurm
Submitted batch job 144
</pre>

You can check the estimated starting time of your job using
<pre>
squeue --start
</pre>

== Submitting a job array ==

In order to submit a array of jobs with the same requirements you have to modify your script file.
The script above is going to spawn 4 jobs each consisting of one srun command. Note the presence of the new environment variable ''${SLURM_ARRAY_TASK_ID}'' which might be useful for your work. In this example we start an isis-script with different input values. You can also simply use different scripts.
<pre>
#!/bin/bash
#SBATCH --partition remeis
#SBATCH --job-name important_job
#SBATCH --ntasks=1
#SBATCH --time 00:05:00
#SBATCH --output /home/dauser/tmp/jobscript_beta.%A_%a.out
#SBATCH --error /home/dauser/tmp/jobscript_beta.%A_%a.err
#SBATCH --array 0-3

cd /home/user/script/

COMMAND[0]="./sim_script.sl 0.00"
COMMAND[1]="./sim_script.sl 0.10"
COMMAND[2]="./sim_script.sl 0.20"
COMMAND[3]="./sim_script.sl 0.30"

srun /usr/bin/nice -n +19 ${COMMAND[$SLURM_ARRAY_TASK_ID]}
</pre>
Note that it is often much better not to hard code the parameters of your job in the batch script, but to move that logic into the simulation script:
<pre>
#!/bin/bash
#SBATCH --partition remeis
#SBATCH --job-name important_job
#SBATCH --ntasks=1
#SBATCH --time 00:05:00
#SBATCH --output /home/dauser/tmp/jobscript_beta.%A_%a.out
#SBATCH --error /home/dauser/tmp/jobscript_beta.%A_%a.err
#SBATCH --array 0-3

cd /home/user/script/
srun /usr/bin/nice -n +19 ./script --param=${SLURM_ARRAY_TASK_ID}
</pre>
In this case, the script will use the command line parameter param to identify what is to be done (all programming languages have ways to access command line parameters, for isis, you might want to take a look at the cmdopt tool, for perl use Getopt::Long, for C use getopt or getopt_long in the Gnu C library, for python use the argparse module).

As above, this code might be saved in a file, for example ''job.slurm'' can be executed using
<pre>
sbatch job.slurm
</pre>

If you need a specific machine to run your job on, you can use
<pre>
#SBATCH --nodelist=leo,draco
</pre>
If you have a job with high I/O and/or traffic on the network you can limit the number of jobs running simultaneously (to 2 in this example) by
<pre>
#SBATCH --array 0-3%2
</pre>
SLURM will only allocate resources on the given nodes. However, if all nodes in 'nodelist' cannot fulfill the job requirements, SLURM will also allocate other machines.

If you would like to cancel jobs 1, 2 and 3 from job array 20 use
<pre>
scancel 20_[1-3]
</pre>
Note that you might have to escape the brackets when using the above command, e.g.,
<pre>
tcsh:~> scancel 20_\[1-3\]
</pre>
If you want to cancel the whole array, ''scancel'' works as usual
<pre>
scancel 20
</pre>
Note, there is also the option to modify requirements of single jobs later using ''scontrol update job=101_1 ...''.

If you have jobs which are dependent on the result of others or if you want a more detailed description concerning job arrays you can find it in the official SLURM manual: [[https://slurm.schedmd.com/job_array.html]]

== Submitting a job array where each command needs to change into a different directory ==

In order to allow each command of the job array to change into an individual directory (as opposed to all into the same directory as above), modify the script as follows:
<pre>
#!/bin/bash
#SBATCH --partition remeis
#SBATCH --job-name important_job
#SBATCH --ntasks=1
#SBATCH --time 00:05:00
#SBATCH --output /home/dauser/tmp/jobscript_beta.%A_%a.out
#SBATCH --error /home/dauser/tmp/jobscript_beta.%A_%a.err
#SBATCH --array 0-3

DIR[0]="/home/user/dir1"
DIR[1]="/home/user/dir2"
DIR[2]="/userdata/user/dir3"
DIR[3]="/userdata/user/dir4"

cd ${DIR[$SLURM_ARRAY_TASK_ID]}

COMMAND[0]="./sim_script.sl 0.00"
COMMAND[1]="./sim_script.sl 0.10"
COMMAND[2]="./sim_script.sl 0.20"
COMMAND[3]="./sim_script.sl 0.30"

srun /usr/bin/nice -n +19 ${COMMAND[$SLURM_ARRAY_TASK_ID]}
</pre>
This also works with paths relative to the directory where the slurm script was submitted.

== Submitting a job array with varying number of tasks ==

This is not really a job "array". But to execute multiple jobs with different number of tasks one can use multiple
srun calls chained with an '&'. This will submit the jobs at once but allow one to specify job parameters individually
for each job.

Example: Simultaneous fit of multiple datasets with different functions

<syntaxhighlight lang="bash" line='line'>
#!/bin/bash
#SBATCH --job-name my_simultaneous_fit_%n
#SBATCH --time 05:00
#SBATCH --output test-job_%A_%a.out
#SBATCH --error test-job_%A_%a.err
#SBATCH --partition=remeis
#SBATCH --mem-per-cpu=100
srun -l my_complicated_fit.sh 2 --ntasks=2 & # my_complicated_fit fits 2 line centers -> needs 2 tasks
srun -l my_complicated_fit.sh 4 --ntasks=4 # my_complicated_fit fits 4 line centers -> needs 4 tasks
</syntaxhighlight>

== Graphical jobs (srun.x11) ==
Not all applications run only on the commandline. Slurm does not support graphical applications natively but there is a wrapper script available which allocates the resources on the cluster and then provides a [[screen]] session inside a running [[SSH|SSH-session]] to the host where the resources have been allocated on. For example
<pre>
[12:06]weber@lynx:~$ srun.x11
</pre>
results in a new shell :
<pre>
[12:06]weber@messier15:~$
</pre>

which forwards the window if you start a graphical program for example
<pre>
[12:06]weber@messier15:~$ kate
</pre>
would open the text editor [[https://de.wikipedia.org/wiki/Kate_(KDE) kate]]. However, this only uses the standard resources set for the remeis partition. If you have other requirements you can also specify these in exactly the same way as for ''srun'':
<pre>
[12:06]weber@lynx:~$ srun.x11 --mem=2G
</pre>
would allocate 2GB of memory for the application.

== Using the ''erosita'' partition (serpens)==

If you are allowed to use the eRosita Partition, contact the admin list. Once your username is added to the list of privileged users, you just have to add
<pre>
#SBATCH --partition=erosita
#SBATCH --account=erosita
</pre>
to your jobfiles.

== Other useful commands ==

* ''sstat'' Real-time status information of your running jobs

* ''sattach <jobid.stepid>'' Attach to stdI/O of one of your running jobs

* ''scancel [OPTIONS...] [job_id[_array_id][.step_id]] [job_id[_array_id][.step_id]...]'' Cancel the execution of one of your job arrays/jobs/job steps.

* ''scontrol'' Administration tool, you can for example use this to modify the requirements of your jobs. You can for exaple show your jobs ''show jobs'' or update the time limit ''update JobId= TimeLimit=2''.

* ''smap'' graphically view information about Slurm jobs, partitions, and set configurations parameters.

* ''sview'' graphical user interface for those who prefer clicking over typing. X-Server required.

= SLURM and MPI =
== About MPI ==
MPI (the Message Passing Interface) makes it possible to run parallel processes on CPUs of different hosts. To do so it uses TCP packets to communicate via the normal network connection. Some tasks can profit a lot of using more cores for computation.
At Remeis MPICH2 is used for initialisation of MPI tasks which is well supported within Slurm. The process manager is called '''pmi2''' and is set as default for srun. If an older MPI process manager is needed, for example for older MPI applications used in '''torque''', it can be set with
<pre>
#SBATCH --mpi=
</pre>
in the submission script.
<pre>
srun --mpi=list
</pre>
provides a list of supported MPI process managers.

The implementation of MPI for SLang/ISIS is called '''SLMPI'''.

== Best practice for MPI tasks ==

The usage of MPI might cause continuously high network traffic especially on the host which holds the master process. Please consider this when deciding which nodes are used for the job. It's a good idea to provide servers (e.g. leo or lupus) with the ''--nodelist='' option one of which is then used to hold the master process since nobody is sitting in front of it and trying to use a browser. Additional nodes are allocated automatically by Slurm if required to fit the ''--ntasks'' / ''-n'' option.

MPI jobs depend on all allocated nodes to be up and running properly, so I'd like to use this opportunity to remind about shutting down/rebooting PCs on your own without any permission can abort a whole MPI job.

== Requirements and Tips ==
To use MPI obviously the application or function used should support MPI. Examples range from programs written in C using some MPI features and compiled with the ''mpicc'' compiler to common ISIS-functions such as ''mpi_emcee'' or ''mpi_fit_pars''.

Keep in mind that everything in the compiled programs/scripts which is not an MPI compatible function is executed on each node on its own. For example in ISIS with ''-n 20'':
<pre>
fit_counts;
</pre>
would fit the defined function to the dataset 20 times at once. That's not very helpful so think about which tasks should be performed in the actual MPI process. Special care has to be taken if something has to be saved as a file. Consider:
<pre>
save_par("test.par");
</pre>
with ''-n 20''. This would save the current fit parameters to '''test.par''' in the working directory 20 times at exactly the same time. This might be helpful if the file is needed on the scratch disk of each node, but doing this on for example ''/userdata'' can cause serious trouble. The function ''mpi_master_only'' can be used to perform a user defined task in an MPI job only once. Best way is to only submit an MPI job to Slurm which only contains actual MPI functions. If some models in ISIS are used which output something to stdout or stderr while loading these messages are also generated 20 times since it's loaded in each process individually.

== Usage ==
If the job is a valid MPI process then the submission works exactly like for any other job:
<pre>
#!/bin/bash
#SBATCH --job-name my_first_mpi_job
#SBATCH ...
#SBATCH --ntasks=20
cd /my/working/dir
srun /usr/bin/nice -n +15 ./my_mpi_script
</pre>
It might be necessary to set a higher memory usage than for the according non MPI job since some applications try to limit the network traffic by just copying the required data to each node in the first place.

Also make sure that if it is necessary to specify the number of child processes in the application itself, set it to the same as with the ''--ntasks'' / ''-n'' option in the submission. An example would be the ''num_slaves'' qualifier in ''mpi_emcee''.

Note that the ''srun'' command does not contain ''mpiexec'' or ''mpirun'' which were used in older versions of MPI to launch the processes. The processes manager ''pmi2'' is built into Slurm and makes it possible that Slurm itself can initialize the network communication with the ''srun'' command only.

Of course it's also possible to run the MPI process directly from the commandline. As an example let's have a look at the calculation of pi with the MPI program ''cpi''. The program comes with the source code of MPICH2 and is compiled in the ''check'' rule. It's located in
<pre>
/data/system/software/mpich/mpich-3.2/examples
</pre>
To run the calculation in 10 parallel processes directly from the commandline use:
<pre>
[1:11]weber@lynx:/data/system/software/mpich/mpich-3.2/examples> srun -n 10 ./cpi
Process 0 of 10 is on aquarius
Process 1 of 10 is on ara
Process 6 of 10 is on asterion
Process 2 of 10 is on ara
Process 8 of 10 is on asterion
Process 7 of 10 is on asterion
Process 3 of 10 is on aranea
Process 5 of 10 is on aranea
Process 4 of 10 is on aranea
Process 9 of 10 is on cancer
pi is approximately 3.1415926544231256, Error is 0.0000000008333325
wall clock time = 0.010601
</pre>
As we can see Slurm launched 10 processes distributed to aquarius, ara, asterion, aranea and cancer. Keep in mind that running MPI interactively doesn't really make sense. The best way to go is to write a submission script like explained above and let Slurm handle the initialisation.

Isis:tutorial:timing

2020-08-10T10:06:08Z

Wilms: Created page with "(this page is work in progress, but it will be a more uniform version of the recipes which are currently available at the Timing tool page of the wiki) === Reading Lightc..."

(this page is work in progress, but it will be a more uniform version of the recipes which are currently available at the [[Timing tool]] page of the wiki)

=== Reading Lightcurves ===

A light curve is a FITS file that contains the information about the brightness of a source as a function of time. Typically, light curves are evenly spaced, that is, the binning of the data does not change with time. The brightness of the source is typically encoded either as a count rate or by the number of events detected in the bin.

This means that FITS light curves contain the following rows:

* ''TIME'': This is the time of the bin. Whether this time is at the start, in the center, or at the end of the bin depends on the value of the header keyword ''TIMEPIXR'', which states the relative time (in units of the binsize - ''TIMEDEL''
* ''RATE'' or ''COUNTS'': This is the count rate of the bin (typically in units of counts/s), or the number of counts.
* ''FRACEXP'': This optional column designates the fractional time that the detector was sensitive in a given time bin. Reasons why ''FRACEXP'' might be less than 1 are, e.g., telemetry drop outs during the time bins or a detector intrinsic dead time. Note that depending on the instrument, the count rate in the ''RATE'' column may or may not be corrected for the ''FRACEXP''. You need to consult the FITS file and/or the documentation of the instrument to find out (often there is a header keyword for this).

In addition to the header keywords ''TIMEPIXR'' and ''TIMEDEL'', the following header keywords are often also used:

* ''MJDREF'': Reference time for the ''TIME''-column. This means that the MJD of the events can be obtained from by the equation MJD=MJDREF+TIME/86400, where it was assumed that the ''TIME''-column is in units of seconds. For high precision lightcurves, the reference MJD is generally encoded in an integer and a fractional part, ''MJDREFI'' and ''MJDREFF''. Use these if they are present. If you need the MJD, use
MJD=MJDREFI+(MJDREFF+TIME/86400.)
Note the parentheses - in pretty much all computing languages derived from C (including S-LANG, python and so on) this enforces that the contents of the parenthesis are computed first, which will reduce the roundoff error.

* ''TSTART'' and ''TSTOP'': Start and end of the observations, in the same units as the ''TIME''-column.

There is unfortunately much less standardization going on with time series than with spectra. This means that all of what is said in the following needs to be taken with a grain of salt, and it is strongly recommended that you take a look at the FITS-file and do not blindly copy the recipes here. One thing that is very important for timing is the question whether the time series contains gaps or not. How these are encoded is mission specific, but in general, a light curve FITS-file will have a Good Time Interval (GTI) extension that lists the valid time intervals. The light curve may or may not be limited to the GTI - for example, some light curves produced by the XMM SAS do NOT limit themselves to the GTI but zero pad the lightcurve. This means that before you work with the time series you have to remove these gaps.

Remeis English Checklist

2020-06-23T08:30:19Z

Wilms: /* Spelling and Word usage */

====== The Remeis English Checklist ======

(by J. Wilms and K. Pottschmidt)

'''''First of all and most importantly:'''''

* did you read the instructions to authors of the journal? If you are working on a thesis, did you read those of [http://www.aanda.org/doc_journal/instructions/aadoc.pdf Astronomy and Astrophysics]?
* did you read appendix A of the [https://journals.aps.org/files/rmpguide.pdf instructions to authors] of Rev Mod Phys?

==== Punctuation ====

* did you remove all commas before "that"?
* did you end your footnotes and captions with a full stop (".")?
* did you make sure that your use of "data" is correct and uses plural verbs?
* did you make sure that you do not have a ":" anywhere before an equation, but that your equations are seen as part of your sentences?
* did you make sure that you have commas surrounding "i.e." and "e.g."?

==== Spelling and Word usage ====

* do you consistently use either British or American spelling?
* did you run a spell checker over your manuscript? For TeX, use "ispell" or the built in spell checker in emacs.
* did you make sure not to use country prefixes in addresses in the author list?
* did you avoid passive voice as much as possible?
* did you make sure that you are //not// using "The found results are..." and similar German constructs in your text?
* did you make sure that everything in your text that is not your original result is accompanied by proper citations?
* did you make sure that you distinguish between "estimate" and "estimation" by replacing all "estimation" with "estimate"?
* did you replace all uses of "exemplary" by "example"?
* did you use "short" for length intervals and "brief" for time intervals? (but note that "short of duration" is correct)
* did you replace all uses of "the actual value" by "the real value"? (if you are German, "actual" does not mean "aktuell"!)
* did you remove all uses of "hence" and "thereby"?
* did you make sure that you use "however" as sparingly as possible?
* did you make sure that you did not use "the equation reads..", but rather used "the equation is..." or "the equation is given by..."?
* did you avoid split infinitives? ("to boldly go..." is wrong; yes, in many cases split infinitives are ok in current English, but they tend to be so often used wrongly by non-native speakers that it is best to avoid them)
* did you make sure that you distinguish properly between "this" and "these"?
* did you make use of the "Oxford comma", i.e., do you have a comma before "and" in lists?
* did you use "i.e." and "e.g." correctly, i.e., using "i.e." for a specific clarification or definition and "e.g." where you would otherwise use "for example"?
* did you use the IAU recommended year - month - day sequences (2016 March 15)?
* did you make sure that you did not use contractions such as "didn't" or "you're"?
* did you replace "cf." with "see" everywhere since you know that "cf." means "compare"?
* did you make sure that the reader will understand what thing you refer to when using "it" rather than naming it?
* did you make sure that all uses of "this" are followed by the object you are referring to?
* did you use "led" rather than "lead" when using the past tense of the verb "to lead"?
* did you reread the manuscript for internal consistency after you added comments from your coauthors?
* did you make sure that your sentences are short (rule of thumb: if a sentence goes over more than three lines it is probably too long)?
* did you check that you did not combine two sentences that could be separate sentences with "and"?
* did you avoid abbreviations as much as possible and only used them when they are really, really common (HST, AGN, XMM,...)?
* did you check that you defined all abbreviations that you used at their first usage? ("...Active Galactic Nucleus (AGN)..." //not// "...AGN (Active Galactic Nucleus)..." )

==== Citations ====

* did you add the journal to all publications where you list the arXiv-reference and not just blindly copy the erroneous ADS bibtex entry?
* did you make sure that you distinguished between arXiv references where a paper is submitted and references where a paper is already accepted by checking the paper author's comment on the arXiv-page for that article?
* did you remove the page number for all ATEL-references downloaded from ADS and changed the journal name to "Astron. Tel." or "ATEL"? (and similar for IAU telegrams)
* did you add editors and the title of the conference publication to all conference publications?
* did you add the publisher and place information (city only) to all books, conference publications, and other book-like publications that you are citing?
* did you check that your references are correct in that you are using ''\citet{biblabel}'' for references in the text and ''\citep{biblabel}'' for references in parentheses?
* did you make sure that none of your ''\citet{..}'' commands refer to more than one biblabel?

==== Typesetting (mainly in TeX) ====

* did you check for missing spaces between values and units?
* did you make sure that all scientific units are typeset in <code>\mathrm</code>?
* did you make sure not to use constructs such as <code>$\mathrm{m}/\mathrm{s}$</code> by using <code>$\mathrm{m}\,\mathrm{s}^{-1}$</code> instead?
* did you make sure that almost all of your error bars are rounded up to only one significant digit rather than following the DIN-norm (which is not applied in astronomical journals)?
* did you make sure that you are not using any positioning commands for the table or figure environment such as <code>\begin{table}[htpb]</code>?
* did you make sure that your tables have captions above the table, and figures have captions below the figure or next to it (where allowed by the style)?
* did you make sure that you use empty lines to denote the start of a new paragraph rather than the ''\\''-command? (use <code>\parindent{0pt}</code> if you do not want to indent paragraphs)
* did you make sure that there are no paragraph endings above or below <code>\begin{equation}...\end{equation}</code> by ensuring that there is no empty line above or below the ''equation''-environment?
* did you make sure that you are not using <code>$\frac{a}{b}$</code> in normal text, but use <code>$a/b$</code> instead?
* did you make sure that you are not using the <code>displaymath</code>-environment and that all equations are numbered?
* did you make sure that all of your sections, subsections, paragraphs and so on are numbered?
* did you avoid any and all uses of <code>\bf</code>, <code>\it</code>, <code>\sl</code>, or <code>\em</code> and use the proper commands <code>\textbf</code>, <code>\textit</code>, <code>\textsl</code>, and <code>\emph</code> instead?
* did you use the en-dash of TeX for ranges, even if they occur in math, by using <code>--</code> in text mode rather than a minus sign? (that is, did you typeset a range in an equation as <code>$3x$--$5x$</code> or <code>$3x\mbox{--}5x$</code> rather than, erroneously, <code>$3x-5x$</code>?
* did you correctly use the minus-sign and dashes in astronomical source names, where the name contains coordinates and the <q>dash</q> really is a southern declination or Galactic latitude, that is, did you typeset <code>Her X-1</code>, <code>LMC X-3</code>, but <code>GX\,339$-$4</code> or <code>IGR J16318$-$4848</code> (and as a really difficult one: <code>MCG$-$6-30-15</code>)?

[[Category:Current Members]]

Category:Isis / Slang

2020-05-24T19:08:16Z

Wilms:

'''This page is being [https://www.sternwarte.uni-erlangen.de/wiki/index.php/Category_talk:Isis_/_Slang discussed].'''

The [[http://space.mit.edu/cxc/isis/ Interactive Spectral Interpretation System (ISIS)]] was developed at MIT for the analysis of X-ray spectra.

Note that this page was just copy-pasted from the old wiki. This is only a short list of instructions that will be available. I do not think that a full list of all instructions should go here for the new wiki, I'm trying to find another solution for that (Matthias: ''What about looking at the content of the category below?'') In the end, I think only the instructions to get isis running and first steps should be here (Matthias: ''I disagree because category pages (like this) are not considered during searches! That's why I have created pages with the "ISIS history file" and "ISISscripts" separately''). I will move all the advanced stuff like defining models, timing tools, etc. somewhere else.
* [[ISIS_introduction_for_the_new_bachelor_students|Introduction for the bachelor students]]
* [[Isis_tutorial|ISIS Tutorial]]
* [[Plotting_with_the_S-Lang_Xfig_module|Plotting with the S-Lang Xfig module, instructions and examples]]
* [[How_to_define_your_own_models_in_ISIS|Define your own models in ISIS]]
* [[Questions_and_Answers| Questions and Answers]]
* [http://www.sternwarte.uni-erlangen.de/git.public/?p=isisscripts;a=history;f=README| README file] for using/.../changing the [http://www.sternwarte.uni-erlangen.de/isis/ ISISscripts]
* [[Timing_tools|Use timing tools with ISIS]]
* [[Parallel_Error_Calculation_using_MPI_and_SLmpi|Parallel Error Calculation using MPI and SLmpi]]
* [[Fake_an_Observation_with_ISIS|fake an observation with isis]]
* [[Fit2dcurve|fit a curve to a 2D data set via parameterized polynomials]]
* [[Simfit|Simultaneous Fits of a large number of observations]]
* [[Fitting_Equivalent_Widths|fitting equivalent widths directly]]
* [[ Emcee|emcee - the Markov-Chain-Monte-Carlo hammer]]
* [[Install_ISIS_on_Mac|install on a MAC OS X (10.10 yosemite) - fresh]]
* [[Making_tables_with_sltable|Quickly generate a LaTeX table of spectral parameters with uncertainties]]
* [[Isis/s-lang video tutorial by F. Fürst]]

== S-Lang tips & tricks ==
* [[Modules | S-Lang modules (function packages)]]
* writing helps for functions
* [[Functions_within_structures|functions within structures]]
* [[Function_nesting|function nesting]]
* [[Self-value_management|self-value-management]]
* [[Changing_qualifiers_before_passing_them_on|changing qualifiers before passing them on]]
* speed up code
** [[Iterating_over_an_array_-_three_different_for-loops|iterating over an array - three different for-loops]]
** [[Ternary_operator_%3F|ternary operator ?: ]]
** [[Profiling|profile - Run-time profiler: Analyses (nested) function run-times]]
* [[Pass_information_to_a_fit_function_via_metadata|passing information to a fit function via metadata]]
* [[References_to_variables|References to variables]]
* [[Name_of_the_calling_function_(ISIS/Slang)| Name of the calling function]]

[[Category:Software]]

Install ISIS on Windows 10

2020-05-24T19:07:25Z

Wilms:

Installing ISIS on Windows is not trivial but thanks to the available Linux subsystem in Windows 10 we can install it like any other Linux program. It is required that the WSL (Windows Subsystem Linux) is activated. Note that if you choose this way you have to compile isis. Using a singularity container will not work.

== TL;DR ==

<ol style="border-style:solid;display:inline-block;padding-left:28px;padding-right:10px;border-color:#aa0505;">
<li> Enable WSL
<ol>
<li> As Administrator start PowerShell (<WinKey> + R and type 'powershell' + <enter>) </li>
<li> Enter <code>dism.exe /online /enable-feature /featurename:VirtualMachinePlatform /all /norestart</code> </li>
<li> Restart your computer </li>
</ol></li>
<li> Install Ubuntu WSL
<ol>
<li> Open the Microsoft Store and search for 'Ubuntu' </li>
<li> Install the latest Ubuntu version </li>
<li> Start the newly installed Ubuntu System (this should provide you with a terminal) and complete the installation steps (enter user name and password) </li>
</ol></li>
<li> Install required software
<ol>
<li> In the newly installed Ubuntu environment type
<pre>sudo apt install -y libreadline-dev libcurl4 libcurl4-gnutls-dev \
libncurses*-dev xorg-dev build-essential gfortran perl-modules python-dev \
pgplot5 libpng-dev libslang2-dev</pre>
This will install all necessary tools to build and use heasoft and isis </li>
<li> We strongly recommend to install s-lang before building isis. The best way to do this is by compiling it by yourself:
<pre>
wget https://www.jedsoft.org/releases/slang/slang-2.3.2.tar.bz2
bzip2 -d slang-2.3.2.tar.bz2
tar xvf slang-2.3.2.tar
cd slang-2.3.2
./configure
make
make install
ldconfig
</pre>
(alternatively, s-lang is also distributed via ubuntu, but this tends to older versions).
<li> Download the heasoft source from
<pre>wget https://heasarc.gsfc.nasa.gov/FTP/software/lheasoft/lheasoft6.27/heasoft-6.27.2src.tar.gz</pre>
Beware: The heasoft package is large and the connection slow so this make take up to several hours.</li>
<li> Unpack the downloaded package with <code>tar xvf heasoft-6.27.2src.tar.gz</code></li>
<li> Enter the build directory
<pre> cd heasoft-6.27.2/BUILD_DIR </pre></li>
<li> Configure the package ...
<pre> ./configure --prefix=$HOME/heasoft </pre></li>
<li> ... build it ...
<pre> make </pre></li>
<li> ... and install
<pre> make install </pre></li>
</ol>
<li> Finally install ISIS
<ol>
<li> Download ISIS: <code>wget https://github.com/houckj/isis/archive/master.zip</code>
and unzip <code>unzip master.zip</code></li>
<li> Enter the directory <code>cd isis-master</code></li>
<li> Make heasoft known to the system
<pre>export HEADAS=$HOME/heasoft/x86_64-pc-linux-gnu-libc2.27/
source $HEADAS/headas-init.sh</pre>
This step is required every time one wants to use ISIS</li>
<li>Configure isis
<pre>./configure --with-headas=$HEADAS --with-cfitsio=$HEADAS --with-slang=/usr --with-pgplot=/usr --prefix=$HOME</pre></li>
<li> And finally
<pre> make && make install </pre>
To install isis in $HOME/isis/1.6.2</li>
</ol>
</li>
</ol>

== Installing an X11 Server to use graphical applications ==

=== TL;DR ===

<ol style="border-style:solid;display:inline-block;padding-left:28px;padding-right:10px;border-color:#aa0505;">
<li> Install Xming from <code>https://sourceforge.net/projects/xming/files/Xming/6.9.0.31/Xming-6-9-0-31-setup.exe/download</code></li>
<li> After Xming is successfully installed launch it and make it known to your linux environment
<pre>export DISPLAY=localhost:0.0</pre></li>
</ol>

[[Category:Isis / Slang]]

Install ISIS on Windows 10

2020-05-24T19:03:45Z

Wilms:

Installing ISIS on Windows is not trivial but thanks to the available Linux subsystem in Windows 10 we can install it like any other Linux program. It is required that the WSL (Windows Subsystem Linux) is activated.

== TL;DR ==

<ol style="border-style:solid;display:inline-block;padding-left:28px;padding-right:10px;border-color:#aa0505;">
<li> Enable WSL
<ol>
<li> As Administrator start PowerShell (<WinKey> + R and type 'powershell' + <enter>) </li>
<li> Enter <code>dism.exe /online /enable-feature /featurename:VirtualMachinePlatform /all /norestart</code> </li>
<li> Restart your computer </li>
</ol></li>
<li> Install Ubuntu WSL
<ol>
<li> Open the Microsoft Store and search for 'Ubuntu' </li>
<li> Install the latest Ubuntu version </li>
<li> Start the newly installed Ubuntu System (this should provide you with a terminal) and complete the installation steps (enter user name and password) </li>
</ol></li>
<li> Install required software
<ol>
<li> In the newly installed Ubuntu environment type
<pre>sudo apt install -y libreadline-dev libcurl4 libcurl4-gnutls-dev \
libncurses*-dev xorg-dev build-essential gfortran perl-modules python-dev \
pgplot5 libpng-dev libslang2-dev</pre>
This will install all necessary tools to build and use heasoft and isis </li>
<li> We strongly recommend to install s-lang before building isis. The best way to do this is by compiling it by yourself:
<pre>
wget https://www.jedsoft.org/releases/slang/slang-2.3.2.tar.bz2
bzip2 -d slang-2.3.2.tar.bz2
tar xvf slang-2.3.2.tar
cd slang-2.3.2
./configure
make
make install
ldconfig
</pre>
(alternatively, s-lang is also distributed via ubuntu, but this tends to older versions).
<li> Download the heasoft source from
<pre>wget https://heasarc.gsfc.nasa.gov/FTP/software/lheasoft/lheasoft6.27/heasoft-6.27.2src.tar.gz</pre>
Beware: The heasoft package is large and the connection slow so this make take up to several hours.</li>
<li> Unpack the downloaded package with <code>tar xvf heasoft-6.27.2src.tar.gz</code></li>
<li> Enter the build directory
<pre> cd heasoft-6.27.2/BUILD_DIR </pre></li>
<li> Configure the package ...
<pre> ./configure --prefix=$HOME/heasoft </pre></li>
<li> ... build it ...
<pre> make </pre></li>
<li> ... and install
<pre> make install </pre></li>
</ol>
<li> Finally install ISIS
<ol>
<li> Download ISIS: <code>wget https://github.com/houckj/isis/archive/master.zip</code>
and unzip <code>unzip master.zip</code></li>
<li> Enter the directory <code>cd isis-master</code></li>
<li> Make heasoft known to the system
<pre>export HEADAS=$HOME/heasoft/x86_64-pc-linux-gnu-libc2.27/
source $HEADAS/headas-init.sh</pre>
This step is required every time one wants to use ISIS</li>
<li>Configure isis
<pre>./configure --with-headas=$HEADAS --with-cfitsio=$HEADAS --with-slang=/usr --with-pgplot=/usr --prefix=$HOME</pre></li>
<li> And finally
<pre> make && make install </pre>
To install isis in $HOME/isis/1.6.2</li>
</ol>
</li>
</ol>

== Installing an X11 Server to use graphical applications ==

=== TL;DR ===

<ol style="border-style:solid;display:inline-block;padding-left:28px;padding-right:10px;border-color:#aa0505;">
<li> Install Xming from <code>https://sourceforge.net/projects/xming/files/Xming/6.9.0.31/Xming-6-9-0-31-setup.exe/download</code></li>
<li> After Xming is successfully installed launch it and make it known to your linux environment
<pre>export DISPLAY=localhost:0.0</pre></li>
</ol>

[[Category:Isis / Slang]]

Isis tutorial installing

2020-05-22T06:53:17Z

Wilms:

====Getting ISIS====
Installing ISIS and all the modules it depends on, is not a trivial task.

We therefore provide a complete isis environment that is pre-installed in a so-called [https://sylabs.io/guides/3.5/user-guide/# singularity environment]. Singularity runs very well under Linux and can also be installed under windows, although this is a bit more complex, which is why we also offer an alternative. Note that you will need about 4 GB of disk space for the installation.

If you do not have enough disk space available or if you are not happy/comfortable with installing software on your computer, we also have an option to run the tutorials on machines at the observatory.

=====Setup for Linux =====
* Install singularity. How you do this depends on the flavor of Linux that you have installed. On ubuntu systems, this is as easy as executing

sudo apt-get install singularity-container

On other Linux versions different commands are required.

* Create a working directory for the lecture and download the singularity image for isis and the other tools required for the tutorial from https://www.sternwarte.uni-erlangen.de/isis/isis-singularity.img , e.g.,

mkdir xray
cd xray
wget https://www.sternwarte.uni-erlangen.de/isis/isis-singularity.img

* you can then launch the singularity environment as follows:
cd xray
singularity run isis-singularity.img

This brings you into an environment that contains most of the relevant X-ray astronomical software, such as, e.g., fv (which you might want to use to display X-ray astronomical data files). You then launch isis by typing '''isis''':

isis

=====Setup for Windows =====

For older windows machines:

* Install singularity using the instructions [https://sylabs.io/guides/3.5/user-guide/# on the singularity homepage]. This is a somewhat involved process, but doable in principle if you are ok with computers. If the instructions don't

* Follow the instructions above.

For Windows 10:
follow the instructions [[Install ISIS on Windows 10|at this link]]. This is fairly advanced, however.

=====Setup for Mac =====

Apple systems claim they are Unix, but they really are not fully compatible to Unix standards. What is worse, there are two different eco systems available for MacOS if you want to compile your own software. And often, only one of them works. If you feel adventurous, you can install the prerequisites on the [https://space.mit.edu/ASC/isis/mac_install.html isis MacOS installation instructions], then [https://heasarc.gsfc.nasa.gov/lheasoft/install.html install HEASoft] (you need to use the source installation), and then go back and install isis.

If you are not experienced in compiling and installing your own software on MacOS, this is not recommended, however, and it is better to ask for an account at the observatory (see below).

=====Working on Remeis observatory computers=====

* If you do not have enough disk space on your computer or do not want to install things locally, contact Ingo Kreykenbohm at the email address given out in the lecture and ask him to create an account on the Remeis computers for you.

* To work on the computers from home, once you have the Remeis account, install the X2go remote desktop environment, following [https://www.sternwarte.uni-erlangen.de/wiki/index.php/X2Go_Remote_Desktop the instructions here].

[[Category:Isis / Slang]]

Isis tutorial installing

2020-05-20T16:42:41Z

Wilms: /* Setup for Windows */

====Getting ISIS====
Installing ISIS and all the modules it depends on, is not a trivial task.

We therefore provide a complete isis environment that is pre-installed in a so-called [https://sylabs.io/guides/3.5/user-guide/# singularity environment]. Singularity runs very well under Linux and can also be installed under windows, although this is a bit more complex, which is why we also offer an alternative. Note that you will need about 4 GB of disk space for the installation.

If you do not have enough disk space available or if you are not happy/comfortable with installing software on your computer, we also have an option to run the tutorials on machines at the observatory.

=====Setup for Linux =====
* Install singularity. How you do this depends on the flavor of Linux that you have installed. On ubuntu systems, this is as easy as executing

sudo apt-get install singularity-container

On other Linux versions different commands are required.

* Create a working directory for the lecture and download the singularity image for isis and the other tools required for the tutorial from https://www.sternwarte.uni-erlangen.de/isis/isis-singularity.img , e.g.,

mkdir xray
cd xray
wget https://www.sternwarte.uni-erlangen.de/isis/isis-singularity.img

* you can then launch the singularity environment as follows:
cd xray
singularity run isis-singularity.img

This brings you into an environment that contains most of the relevant X-ray astronomical software, such as, e.g., fv (which you might want to use to display X-ray astronomical data files). You then launch isis by typing '''isis''':

isis

=====Setup for Windows =====

For older windows machines:

* Install singularity using the instructions [https://sylabs.io/guides/3.5/user-guide/# on the singularity homepage]. This is a somewhat involved process, but doable in principle if you are ok with computers. If the instructions don't

* Follow the instructions above.

For Windows 10:
follow the instructions [[Install ISIS on Windows 10|at this link]]. This is fairly advanced, however.

=====Working on Remeis observatory computers=====

* If you do not have enough disk space on your computer or do not want to install things locally, contact Ingo Kreykenbohm at the email address given out in the lecture and ask him to create an account on the Remeis computers for you.

* To work on the computers from home, once you have the Remeis account, install the X2go remote desktop environment, following [https://www.sternwarte.uni-erlangen.de/wiki/index.php/X2Go_Remote_Desktop the instructions here].

[[Category:Isis / Slang]]

Isis tutorial walkthrough

2020-05-19T13:57:48Z

Wilms:

== A Walk Through ISIS ==

In this first part of the tutorial, in order to get you started we will show you an example for a full X-ray data analysis using a fairly simple spectrum<ref>this section is mainly based on [http://space.mit.edu/home/mnowak/isis_vs_xspec/ Mike Nowak's introduction to isis]</ref>.

In the following tutorial, we will be working on a simple data set from an observation of a black hole, Cygnus X-1, that was obtained with NASA's Rossi X-ray Timing Explorer satellite. The test data set can be downloaded from [http://www.sternwarte.uni-erlangen.de/~wilms/isistut/ here]. It consists of the following parts:
* <code>standard2f_0134off_top.pha</code> -- the spectrum itself. The data are in FITS-format, a standard file format that is used in all of astronomy. Right now you can treat these files as a black box, at the end of this document there is some additional information about how to inspect the contents of these files outside of isis.

=== Invoking isis ===

Isis is a command-line program and is therefore usually executed from the command line (the details are explained in the installation instructions):
<pre>
wilms@leo:~> isis
</pre>
which then prints out some start up messages before you end with the isis prompt:
<pre>
Welcome to ISIS Version 1.6.2-44
Copyright (C) 1998-2020 Massachusetts Institute of Technology

Isis web page: http://space.mit.edu/cxc/isis/
Mailing list archive: http://space.mit.edu/cxc/isis/archive/
Send questions to the mailing list: <isis-users@space.mit.edu>.
For a summary of recent changes, type: "help changes"

isis>
</pre>
As part of its startup, isis executes a file called [[ISIS auto start (.isisrc)|.isisrc]], which is useful for setting up a standard environment.

In the following we will show you an interactive session with isis. It is the typical approach when working with new data to look at these first by hand, in a way similar to that shown here. In later, more advanced analysis you will probably mainly interact with isis through programs, although it should be emphasized that working interactively with data first is always a good idea. This is the only way how you can get a good feeling for your data, even though automated reductions ''are'' important, especially when working on data sets with many different observations.

For a more formal walk through through isis and the programming language s-lang, take a look at the [http://space.mit.edu/cxc/isis isis web page], especially the [https://space.mit.edu/cxc/isis/docs.html documentation] available there.

=== Loading and Inspecting Your Data Set ===

We now load the data we looked at before into isis:
<pre>
pca=load_data("standard2f_0134off_top.pha");
</pre>
The <code>load_data</code> command loads the file given as its argument and returns an unique number that identifies this data set. In the above example, this identifier is stored in the variable called <code>pca</code> (it usually makes sense to use the name of the detector with which the data were taken, although there are exceptions). Note that the command ends with a semicolon. This is standard in slang, the language on which isis is based. Although it is in principle possible to switch off this feature when working interactively with isis<ref>since you are curious: put<pre>Isis_Append_Semicolon=1;</pre> in your <code>~/.isisrc</code></ref>, we recommend you do not use this option -- having to type the semicolon requires you to think before doing something, which is generally a good idea ;-).

If all goes fine, you will be informed that the response matrix includes the ARF. Now check whether isis loaded what you think it should have loaded by looking at some basic information about the background file, the RMF, and the ARF:
<pre>
isis> list_data;
Current Spectrum List:
id instrument part/m src use/nbins A R totcts exp(ksec) target
1 PCA 0 129/ 129 - 1 3.1773e+06 2.528 CYG_X-1
file: standard2f_0134off_top.pha
back: standard2f_back_SkyVLE_top_good_0134off.pha
</pre>
Amongs others, the table columns include
* <code>id</code>: the identifier of this data set,
* <code>nbins</code>: the number of spectral bins,
* <code>totcts</code>: the total counts in the spectrum,
* <code>exp</code>: the exposure time in kiloseconds, and
* <code>target</code>: the nominal source we are working with.
Finally, the output also lists the file name and the associated background file.

Similar information can also be obtained for the response matrix and the ARF using the commands
<pre>
list_rmf;
list_arf;
</pre>
Note that for your data set no information is given back for the ARF, since none was loaded.

Like for all commands in isis, information about the commands can be obtained with
<pre>
isis> help commandname
</pre>
so, for example,
<pre>
isis> help list_arf
</pre>
(If this does not give you help for the command you put in, you can try just
<pre>
isis> commandname;
</pre> without any additional arguments. For some commands that works.)
Some of the help information might appear pure gibberish for you. Ignore this for the moment, with time it will all become clear to you.

A second help function that is very useful is the <code>apropos</code> command. For example, if you want to do something with an ARF, do
<pre>
isis> apropos arf
</pre>
which will return all isis commands that contain "arf" in their name.

'''''Exercise 1'''''
# Load your data set and check that the information given by ISIS using the above commands is identical to the information that you obtained in the previous exercise.

=== Plotting the Data ===

X-ray data analysis of a data set that you do not yet know consists basically of the following steps:
# plot something
# think about what the plot/data set tries to tell you
# try something out (e.g., perform a fit)
# goto 1
and then repeat until you are convinced that everything works as expected. Depending on the data set, the above might take five minutes, but we also had complicated data sets that so far have resulted in 2-3 PhD theses...

Therefore, as the first step, we take a look at our data.

While isis contains some basic plotting routines, it is generally faster to use the very powerful plotting routines developed at MIT and at Remeis/ECAP to look at the data. The reason is that these are more user friendly than the basic isis routines.

In order to do so, we first need to load the Remeis isis scripts. In our standard install, just do a
<pre>
isis> require("isisscripts");
</pre>
The <code>isisscripts</code> are a large set of useful routines developed by many people. If you use them for professional work, please contact J. Wilms first and ask whom to put in the acknowledgments of your paper. They are freely available through a git-repository.

So let's plot the data set:
<pre>
isis> plot_counts(pca);
</pre>
A window pops up, looking something like this

[[File:Walkthrough01.png|center]]

In this standard display, not much can be seen except for the fact that the detector sensitivity is the best at low energies. For this reason, we first switch the plot over to a log-log plot and plot again:
<pre>
isis> xlog;
isis> ylog;
isis> plot_counts(pca);
</pre>
This results in a much nicer plot. With the exception of gratings data, it is usually better to take a look at X-ray data in log-log space, so you should get used to switching over to log-space before doing any plots:

[[File:Walkthrough02.png|center]]

Note that what is shown are counts per PHA bin as a function of energy. Here, the response matrix is used to get an approximate conversion of the channel number to energy. The jump at around 20keV is not a spectral feature, but caused by the detector: at this energy, the standard data mode on RXTE PCA increases the energy width per PHA bin by a factor of two. Since the spectrum changes only slowly at this energy, because of the increase in width twice as many counts are detected in this bin. In addition, the feature at around 30keV is also a detector feature, it mainly reflects the change in sensitivity of this Xe-based proportional counter at the Xe-K-edge, which is at roughly 30keV.

Experience for this detector shows that its calibration is best at energies between 3keV and 22keV, such that for the moment we will ignore what is happening outside of this energy band using isis' <code>notice</code> function:
<pre>
isis> notice_values(pca,3.,22.;unit="keV");
isis> plot_counts(pca);
</pre>
Note that immediately after ignoring, we plot the data again in order to make sure that our command worked as intended. This way you can visually confirm, e.g., that a feature that you want to ignore really was outside of the energy range considered. Furthermore, note that we are explicitly telling isis to work in energy space. This is necessary since for historic reasons many isis commands are by default working in wavelength space.

Other useful isis commands for noticing and ignoring energy and wavelength ranges are
<pre>
ignore(id); % Ignore dataset id
notice(id,a,b); % Notice wavelength range [a,b] in dataset id
notice_en(id,a,b); % Notice energy range [a,b] in dataset id
xnotice(id,a,b); % *Only* notice wavelength range [a,b] in dataset id
xnotice_en(id,a,b); % *Only* notice energy range [a,b] in dataset id
exclude(id); % Don't change the ignored/noticed channels, but
% exclude the whole data set until reinstated with:
include(id); % Reinstate the data with prior excluded channels
</pre>
You can get more information about all of these commands with the <code>.help</code>-command. Note that all of the above commands are "inclusive", in the sense that the energy bins in the spectrum that include the two borders, a and b, are contained in the noticed energy band.

'''''Exercise 2'''''
# Perform the above steps for your data set. In the write up of your homework, include the relevant figures. Prepare these figures as publication-quality (postscript) figures. For this you will have to switch the output to postscript before plotting, and switch back to screen output afterwards:
<pre>isis>plotid = open_print("example.ps/vcps");
isis> keynote_size; nice_width;
isis> plot_counts(pca);
isis> close_print(plotid);
</pre> where <code>example.ps</code> is the file name of the postscript file, and where <code>keynote_size</code> and <code>nice_width</code> set the size of the figure to something that is appropriate for inclusion into a journal article. If you rather work with pdf, convert the ps-file to pdf afterwards, e.g., using Linux <code>epstopdf</code> program.

=== Inspecting ARF and RMF ===

It is always useful in data analysis to have a feeling for the major features introduced by specific properties of the detector used to measure the data. For example, in the spectra above there are drops in detector sensitivity at the K- and L-edges of the detector gas. Usually, the regions around these edges are less well calibrated. Visualizing the ARF and RMF helps in this case (as does reading the user's manual for the satellite you're using...).

It is easy to produce a plot of the RMF:
<pre>
isis> fits_plot_rmf("p2_LR1_2009-05-06.rsp");
</pre>

The resulting plot should be similar to this:

[[File:Rmf.png|center]]

To visualize the sensitivity of the detector we need to plot the effective area of the detector as a function of energy. Depending on the instrument, the detector sensitivity is either saved as a separate ARF (Ancilliary Response File) or it is stored as part of the RMF. In the latter case isis will tell you so with the warning message "RMF includes the effective area" when you load the response. In this case we need to factor the response first:
<pre>
isis> rsp=load_rmf("p2_LR1_2009-05-06.rsp");
RMF includes the effective area
isis> arf=factor_rsp(rsp);
</pre>

We can then get the information about the effective area and plot it:
<pre>
isis> arfdata=get_arf(arf);
isis> xlog;
isis> hplot(_A(arfdata));
</pre>

where the function _A converts the wavelength information contained in the structure arfdata to keV.

[[File:Arf.gif|center]]

=== Performing a First Spectral Fit ===

We are now ready to perform a first spectral fit. We first need to define the spectral model that we want to describe our data with. In general, one first tries to get a rough description of the data, which is for example based on earlier observations of the object and general astrophysical knowledge about the class of objects - if present -, and then refines this spectral model by adding further spectral components if an initial fit was successful. Isis includes a large number of spectral models. Since the models are derived from XSPEC, a good overview is given by the exhaustive list of the models in the [https://heasarc.gsfc.nasa.gov/xanadu/xspec/manual/XspecManual.html XSPEC manual].

What model to use depends on the object one looks at. In most cases, one tries either a power law or a black body first and only later works with more CPU-intensive, physics-based models. Since all X-ray sources are absorbed by the interstellar medium in our Galaxy, one ''always'' includes Galactic absorption.

Here, we know that Cygnus X-1 is a black hole. These often have power-law spectra. We therefore start by trying an absorbed power-law as our fit function:
<pre>
isis>fit_fun("tbabs(1)*powerlaw(1)");
</pre>
Notice the numbers behind the model components. These will be later used to distinguish different fit-functions, e.g., when one works with a source that has a spectrum that can be described as the sum of two power laws of different photon indices.

Next we take a look at our fit parameters:
<pre>
isis> list_par;
tbabs(1)*powerlaw(1)
idx param tie-to freeze value min max
1 tbabs(1).nH 0 0 1 0 100000 10^22
2 powerlaw(1).norm 0 0 1 0 1e+10
3 powerlaw(1).PhoIndex 0 0 1 -2 9
</pre>
Amongst other information, which we will be discussing in a later tutorial, the table contains the following information:
* <code>idx</code>: The index of the parameter (see below)
* <code>param</code>: The name of the parameter. For example, <code>tbabs(1).nH</code> is the absorption column (in units of 10^22 cm-2. The physical meaning of the parameters is explained in the [https://heasarc.gsfc.nasa.gov/xanadu/xspec/manual/XspecManual.html XSPEC manual].
* <code>tie-to</code> and <code>freeze</code>: see later
* <code>value</code>: the current value of the parameter
* <code>min</code> and <code>max</code>: The fit has to remain in the range between these two values.

Before we do our first fit, we take a look at how this model looks like when folded through the detector response matrix. In order to do so we first ask isis to change the model flux such that the predicted count rate is close to the model count rate.
<pre>
isis> renorm_counts;
:
Parameters[Variable] = 3[1]
Data bins = 45
Chi-square = 898942.6
Reduced chi-square = 20430.51
0
</pre>
Isis has changed the parameter <code>powerlaw(1).norm</code> and has left all other parameters unchanged:
<pre>
isis> list_par;
tbabs(1)*powerlaw(1)
idx param tie-to freeze value min max
1 tbabs(1).nH 0 0 1 0 100000 10^22
2 powerlaw(1).norm 0 0 0.4145608 0 1e+10
3 powerlaw(1).PhoIndex 0 0 1 -2 9
</pre>
Now let us take a look at what the model looks like
<pre>
isis> plot_counts(pca);
</pre>
The resulting plot looks something like this:

[[File:Walkthrough03.png|center]]

Notice that the slope of the spectrum and the data is very different. With a photon index of 1 the spectrum is harder than the data. We therefore change the photon index to something that is more typical for black holes, renorm the spectrum and plot it again:
<pre>
isis> set_par(3,1.7);
isis> renorm_counts;
Parameters[Variable] = 3[1]
Data bins = 45
Chi-square = 339671.5
Reduced chi-square = 7719.808
0
isis> plot_counts(pca);
</pre>
The resulting model looks like this:

[[File:Walkthrough04.png|center]]

Note that the overall slope now looks ok, but there is still some deviation between the data and the model at the soft part of the spectrum, where the model looks too much absorbed. Taking a look at the isis help for <code>set_par</code>, we are being told that instead of changing the parameter by giving <code>set_par</code> its index number, we could also have given the full name of the parameter. So let us remove some absorption to get the curvature at the low energies right, by setting NH to its interstellar value of <latex>N_\mathrm{H}=3\times 10^{21}\,\mathrm{cm}^{-2}</latex>.
<pre>
isis> set_par("tbabs(1).nH",0.3);
isis> renorm_counts;
Parameters[Variable] = 3[1]
Data bins = 45
Chi-square = 314595.1
Reduced chi-square = 7149.888
0
isis> plot_counts(pca);
</pre>
Note that the Chi-square value decreased, meaning that the new description of the model is slightly better than the previous one.

We now have starting values that are good enough to start the proper fitting. Here isis is using a so-called Levenberg-Marquardt-gradient method to minimize chi-square by varying the parameters. This is done step by step, until a (possibly local) minimum is reached. In order to see how the parameters are being varied, we instruct isis to display all intermediate parameter values first, and then perform the fit:
<pre>
isis> Fit_Verbose=1;
isis> fit_counts();
chisqr= 3.1460e+05:
tbabs(1).nH= 3.00000000e-01 powerlaw(1).norm= 2.26407499e+00
powerlaw(1).PhoIndex= 1.70000000e+00
chisqr= 3.1460e+05:
tbabs(1).nH= 3.00030000e-01 powerlaw(1).norm= 2.26407499e+00
powerlaw(1).PhoIndex= 1.70000000e+00
:
: multiple further steps
:
chisqr= 9.6239e+03:
tbabs(1).nH= 0.00000000e+00 powerlaw(1).norm= 1.32707632e+01
powerlaw(1).PhoIndex= 2.61135748e+00
chi-square value converged
Parameters[Variable] = 3[3]
Data bins = 45
Chi-square = 9623.869
Reduced chi-square = 229.1397
0
</pre>
While the reduced chi-square is already much smaller, it is still very much above its ideal value of around unity. Let us take a look what the current best fit looks like by plotting it again:

[[File:Walkthrough05.png|center]]

The model describes the overall shape of the data rather well, but statistically significant residuals remain. We will tackle these in the next section, but first let us save our work so far such that we can start again from the current best fit in case our next steps are not successful:
<pre>
isis> save_par("powerlaw.par");
</pre>
This creates a file called <code>powerlaw.par</code> that can be re-read later using
<pre>
isis> load_par("powerlaw.par");
</pre>
The file is a simple ASCII file that you can either just display on screen (using the unix-command <code>cat powerlaw.par</code> from the shell or any editor of your choice.

'''''Exercise 3'''''
# Perform the procedure described above with "your" data set, documenting all steps.
# If you want to change more than one parameter at a time, instead of using <code>set_par</code> you can also use the <code>edit_par</code> function, which will invoke an editor of your choice with a table like the parameter table above. You can then overwrite all values with your new values, save this temporary file, and exit the editor. Try this with your data set.

=== Improving the Initial Fit ===

Now that we have an initial fit, we can take a closer look at the difference between the data and the model to get a feeling what we can do to improve the model. Since the data values and the model are already rather close together, guessing what is going on by looking at the slight differences between both is not very useful. We therefore plot our data again, but this time not only displaying the data but also the "residuals", that is the difference between the data and the model:
<pre>
isis> plot_data(pca;res=1);
</pre>
This results in the following figure:

[[File:Walkthrough06.png|center]]

Note the following:
* instead of using <code>plot_counts</code> we have used <code>plot_data</code> (which is in reality an alias for the <code>plot_data_counts</code> function). <code>plot_data</code> displays the counts and the model in terms of counts per keV, while previously we used counts per PHA bin. This is the preferred way to plot X-ray data, since it is slightly closer to showing the proper spectrum than <code>plot_counts</code>.
* Secondly, in addition to plotting the data we are also plotting the residuals, by using the "qualifier" <code>res=1</code>. In Slang/isis, qualifiers are special switches in functions. They all have names (<code>res</code> in the above example), i.e., the order in which they are listed after the initial semicolon does not matter. The most important ways of displaying residuals are
** <code>res=1</code>: Display the residual in terms of chi, i.e., display the value of <latex>(data-model)/\sigma</latex> where <latex>\sigma</latex> is the statistical uncertainty of the bin.
** <code>res=3</code>: Display the ratio between the data and the model, <latex>data/model</latex>.
* other qualifiers that are useful in plotting are:
** <code>mcol=number</code>: the color of the model, number is, well, a number. Avoid <code>mcol=3</code> and <code>mcol=5</code> since these colors do not show up on beamers.
** <code>dcol=number</code>: dito, for the data
** <code>decol=number</code>: dito, for the error bars
** <code>bkg</code>: if <code>bkg=0</code> then plot the data with the background subtracted, if <code>bkg=1</code> also show the background (this will be useful later).
** <code>xrange={min,max}</code>: plot the x-axis from min to max only. Note the curly braces! Set <code>min</code> and/or <code>max</code> to <code>NULL</code> if you want to reset this range to its default value. It is important to remember that <code>xrange</code> just sets the ''plot''-range, you need to use <code>notice</code> to set the energy range that is used for fitting.
** <code>yrange={min,max}</code>: dito, for the y-axis.

As an example, try
<pre>
isis> plot_data(pca;res=1,mcol=2,dcol=1,decol=5);
</pre>

The residuals in the plot tell us two things:
- there is a "bump" around 6.4keV. This is typically an indication that there is an iron Kα line present around 6.4keV.
- there is a "soft excess" at low energies, which might be indicative of an accretion disk.

Looking at the [https://heasarc.gsfc.nasa.gov/xanadu/xspec/manual/XspecManual.html XSPEC] manual tells us that accretion disk spectra are modeled with the <code>diskbb</code> model while emission lines are modeled using the <code>gauss</code> model. However, reading the isis manual tells us that the ''only'' model that has a different name in isis and in XSPEC is <code>gauss</code> where we will have to use <code>egauss</code> instead.

Based with this information we setup the new fit function as follows
<pre>
isis> fit_fun("tbabs(1)*(diskbb(1)+egauss(1)+powerlaw(1))");
</pre>
and identify the new parameters with <code>list_par</code>:
<pre>

isis> list_par;
tbabs(1)*(diskbb(1)+egauss(1)+powerlaw(1))
idx param tie-to freeze value min max
1 tbabs(1).nH 0 0 0 0 100000 10^22
2 diskbb(1).norm 0 0 1 0 1e+10
3 diskbb(1).Tin 0 0 1 0 1000 keV
4 egauss(1).area 0 0 1 0 0 photons/s/cm^2
5 egauss(1).center 0 0 1 0 0 keV
6 egauss(1).sigma 0 0 0.002 1e-06 1 keV
7 powerlaw(1).norm 0 0 13.27076 0 1e+10
8 powerlaw(1).PhoIndex 0 0 2.611357 -2 9
</pre>
We then set the center of the Gaussian to 6.4keV (<code>set_par(5,6.4);</code>) and plot again. Nothing changes. The reason is that we first have to tell isis to recalculate the model. Not doing this automatically after every invocation of <code>set_par</code> makes sense since some models might take up large amounts of CPU time. To recalculate the model, use
<pre>
isis> eval_counts;
</pre>
Plot the model again (using <code>plot_data</code>). You will notice that the Fe line is too strong. Reduce its flux accordingly by changing the <code>area</code> parameter. You will probably need a few attempts to get something that looks ok. Then repeat this procedure with the parameters of the accretion disk until you get something that looks halfway ok. Save this attempt, just to be on the save side, and then perform a fit.

Repeating the above a few times, I managed to coax the following best fit out of the data
<pre>
isis> list_par;
tbabs(1)*(diskbb(1)+egauss(1)+powerlaw(1))
idx param tie-to freeze value min max
1 tbabs(1).nH 0 0 0 0 100000 10^22
2 diskbb(1).norm 0 0 4088.32 0 1e+10
3 diskbb(1).Tin 0 0 0.7163385 0 1000 keV
4 egauss(1).area 0 0 0.07462147 0 0 photons/s/cm^2
5 egauss(1).center 0 0 6.085836 0 0 keV
6 egauss(1).sigma 0 0 1 1e-06 1 keV
7 powerlaw(1).norm 0 0 2.948465 0 1e+10
8 powerlaw(1).PhoIndex 0 0 1.984697 -2 9
</pre>
with
<pre>
Parameters[Variable] = 8[8]
Data bins = 45
Chi-square = 291.7067
Reduced chi-square = 7.883964
</pre>
This fit looks the following:

[[File:Walkthrough07.png|center]]

This is quite ok for such a simple model. Note that there still is some hardening above 10keV and the residuals are not perfect around 8keV either. This is due to the too large width of the simple Gaussian line, limitations in the <code>diskbb</code>-model, and the fact that in this data set the source was in its intermediate state, where the combination of the disk component and the power law is notoriously hard to model.

'''''Exercise 4'''''
# you guessed it: try to find a good fit for your data set.

=== Inspecting your data set outside of isis ===

You can take a look at what such a file looks like using the <code>fv</code> or <code>fdump</code> programs, which are part of HEASOFT and should already be installed on your machine. ''Outside'' of isis, invoke fv with <pre>fv standard2f_0134off_top.pha</pre> A window pops up that displays the contents of the file. Like all FITS files PHA<ref>"PHA" stands for ''pulse height analyzer'', since X-ray data do usually not contain real energy or wavelength information, since the limited resolution of X-ray detectors does usually not allow directly measuring the photon's energy with high precision</ref> files consist of a so-called primary-header and then multiple extensions, which again contain some human-readable header data that contain information about your data set and the data itself. The header information is given as a keyword name, the value of the keyword, and often a comment that describes the meaning of the keyword. Important keywords are
** <code>OBJECT</code>: The name of the observed object (a string defined by the observer, often - but not always - a meaningful name)
** <code>RA_OBJ</code> and <code>DEC_OBJ</code>: The position of the object (often useful if the <code>OBJECT</code>-keyword is not set or wrong)
** <code>TELESCOP</code> and <code>INSTRUME</code>: The satellite and instrument used
** <code>DATE-OBS</code> and <code>DATE-END</code>: The date and time of the start and the end of the observation
** <code>EXPOSURE</code>: The exposure time, i.e., how long were data accumulated. Note that often <code>EXPOSURE</code> is smaller than the difference between <code>DATE-OBS</code> and <code>DATE-END</code> since the detector could have been switched off for part of the observation, or data were discarded during the data reduction, e.g., because of large background fluxes<ref>The full information about the times during which the data in the spectrum were accumulated is contained in the so-called GTI (good time intervals) extension of the PHA-file</ref>.
** <code>BACKFILE</code>: The name of the PHA-file that defines the background, which is automatically subtracted from the data before fitting.
** <code>RESPFILE</code>: The name of the file containing the detector response matrix (often called "RMF" or "RSP", which describes the mapping from PHA-space to energy space and all detector effects.
** <code>ANCRFILE</code>: The name of the ancilliary response file, often called ARF-file. This file is used by some instruments which separate the detector response into a pure energy redistribution matrix and an effective area. See the X-ray astronomy lectures for details. This keyword has the value <code>NONE</code> if the ARF is already part of the response matrix.
** Further keywords depending on the satellite (often one finds, e.g., <code>TSTART</code> and <code>TSTOP</code> which contain the same information as <code>DATE-OBS</code> and <code>DATE-END</code>, only in a system that is easier to use in calculation than the human-readable information in <code>DATE-OBS</code> and <code>DATE-END</code>).
* <code>standard2f_back_SkyVLE_top_good_0134off.pha</code>: The background spectrum referred to in the <code>BACKFILE</code> keyword of <code>standard2f_0134off_top.pha</code>
* <code>p2_LR1_2010-07-04.rsp</code>: The response matrix referred to in the <code>RESPFILE</code> keyword of <code>standard2f_0134off_top.pha</code>

As mentioned above, you can either take a look at the files with <code>fv</code>, or by dumping the FITS-file on the screen using the <code>fdump</code> command. Here is the output of the latter, showing typical values of the keywords above:
<pre>
wilms@leo:~/isistut> fdump standard2f_0134off_top.pha
Name of optional output file[STDOUT]
Names of columns[]
Lists of rows[-]
SIMPLE = T / file does conform to FITS standard
BITPIX = -32 / number of bits per data pixel
NAXIS = 0 / number of data axes
EXTEND = T / FITS dataset may contain extensions
COMMENT FITS (Flexible Image Transport System) format is defined in 'Astronomy
COMMENT and Astrophysics', volume 376, page 359; bibcode: 2001A&A...376..359H
:
: ... many further lines
:
XTENSION= 'BINTABLE' / binary table extension
BITPIX = 8 / 8-bit bytes
:
:
EXTNAME = 'SPECTRUM' / name of this binary table extension
:
TELESCOP= 'XTE ' / Telescope (mission) name
INSTRUME= 'PCA ' / Instrument name
FILTER = 'NONE ' / Instrument filter in use
EXPOSURE= 2.52800000000001E+03 / Exposure time
:
BACKFILE= 'standard2f_back_SkyVLE_top_good_0134off.pha' / Background FITS file f
CORRFILE= 'standard2f_back_SkyVLE_top_good_0134off.pha' / Correlation FITS file
RESPFILE= 'p2_LR1_2010-07-04.rsp' / Redistribution matrix file (RMF)
ANCRFILE= 'NONE ' / Ancillary response file (ARF)
:
CREATOR = 'SAEXTRCT version 4.2g' / Program name that produced this file
DATE = '2011-06-26T10:08:03' / file creation date (YYYY-MM-DDThh:mm:ss UT)
RA_OBJ = 2.99591705E+02 / RA of First input object
DEC_OBJ = 3.52016983E+01 / DEC of First input object
EQUINOX = 2000.00 / Equinox of the FIRST object
:
DATASUM = '3317156129' / data unit checksum updated 2011-06-26T10:08:03
END

CHANNEL COUNTS STAT_ERR
count count
1 0 2.860600000000000E+04 1.691330836944682E+02
</pre>
The data themselves give, for each PHA-channel, the number of counts measured in the <code>COUNTS</code> column and the uncertainty of the data in the <code>STAT_ERR</code> column. If the data have not been background subtracted before the analysis, which is typical for most instruments except for data from coded mask telescopes, then <code>STAT_ERR</code> will usually have been determined assuming Poisson-statistics, i.e., it is the square-root of the value in <code>COUNTS</code>.

There are many more useful programs to inspect FITS-files. You can get an overview of what is available using
<pre>
wilms@leo:~/isistut> fhelp ftools
</pre>
and if you only want to see the list of general (non satellite-specific) tools
<pre>
wilms@leo:~/isistut> fhelp futils
</pre>
Full information on individual ftools can be obtained with <code>fhelp toolname</code>, e.g.,
<pre>
wilms@leo:~/isistut> fhelp fdump
</pre>
Other useful tools for inspecting FITS-files are, e.g., <code>fstruct</code> and <code>fstatistic</code>.

'''''Optional Exercise 1'''''
# For your example data set, determine the date of the observation, the exposure time, and the name of the background file.
# Use <code>fstruct</code> to determine the structure of the backgrund file and confirm that it is the same as the structure of the PHA file containing the data.

=== References ===
[[Category:Isis / Slang]]

Isis tutorial walkthrough

2020-05-19T13:40:15Z

Wilms: /* Invoking isis */

== A Walk Through ISIS ==

In this first part of the tutorial, in order to get you started we will show you an example for a full X-ray data analysis using a fairly simple spectrum<ref>this section is mainly based on [http://space.mit.edu/home/mnowak/isis_vs_xspec/ Mike Nowak's introduction to isis]</ref>.

=== Inspecting your data set outside of isis ===

In the following tutorial, we will be working on a simple data set from an observation of a black hole, Cygnus X-1, that was obtained with NASA's Rossi X-ray Timing Explorer satellite. The test data set can be downloaded from [http://www.sternwarte.uni-erlangen.de/~wilms/isistut/ here]. It consists of the following parts:
* <code>standard2f_0134off_top.pha</code> -- the spectrum itself. The data are in FITS-format, a standard file format that is used in all of astronomy. You can take a look at what such a file looks like using the <code>fv</code> or <code>fdump</code> programs, which are part of HEASOFT and should already be installed on your machine. ''Outside'' of isis, invoke fv with <pre>fv standard2f_0134off_top.pha</pre> A window pops up that displays the contents of the file. Like all FITS files PHA<ref>"PHA" stands for ''pulse height analyzer'', since X-ray data do usually not contain real energy or wavelength information, since the limited resolution of X-ray detectors does usually not allow directly measuring the photon's energy with high precision</ref> files consist of a so-called primary-header and then multiple extensions, which again contain some human-readable header data that contain information about your data set and the data itself. The header information is given as a keyword name, the value of the keyword, and often a comment that describes the meaning of the keyword. Important keywords are
** <code>OBJECT</code>: The name of the observed object (a string defined by the observer, often - but not always - a meaningful name)
** <code>RA_OBJ</code> and <code>DEC_OBJ</code>: The position of the object (often useful if the <code>OBJECT</code>-keyword is not set or wrong)
** <code>TELESCOP</code> and <code>INSTRUME</code>: The satellite and instrument used
** <code>DATE-OBS</code> and <code>DATE-END</code>: The date and time of the start and the end of the observation
** <code>EXPOSURE</code>: The exposure time, i.e., how long were data accumulated. Note that often <code>EXPOSURE</code> is smaller than the difference between <code>DATE-OBS</code> and <code>DATE-END</code> since the detector could have been switched off for part of the observation, or data were discarded during the data reduction, e.g., because of large background fluxes<ref>The full information about the times during which the data in the spectrum were accumulated is contained in the so-called GTI (good time intervals) extension of the PHA-file</ref>.
** <code>BACKFILE</code>: The name of the PHA-file that defines the background, which is automatically subtracted from the data before fitting.
** <code>RESPFILE</code>: The name of the file containing the detector response matrix (often called "RMF" or "RSP", which describes the mapping from PHA-space to energy space and all detector effects.
** <code>ANCRFILE</code>: The name of the ancilliary response file, often called ARF-file. This file is used by some instruments which separate the detector response into a pure energy redistribution matrix and an effective area. See the X-ray astronomy lectures for details. This keyword has the value <code>NONE</code> if the ARF is already part of the response matrix.
** Further keywords depending on the satellite (often one finds, e.g., <code>TSTART</code> and <code>TSTOP</code> which contain the same information as <code>DATE-OBS</code> and <code>DATE-END</code>, only in a system that is easier to use in calculation than the human-readable information in <code>DATE-OBS</code> and <code>DATE-END</code>).
* <code>standard2f_back_SkyVLE_top_good_0134off.pha</code>: The background spectrum referred to in the <code>BACKFILE</code> keyword of <code>standard2f_0134off_top.pha</code>
* <code>p2_LR1_2010-07-04.rsp</code>: The response matrix referred to in the <code>RESPFILE</code> keyword of <code>standard2f_0134off_top.pha</code>

As mentioned above, you can either take a look at the files with <code>fv</code>, or by dumping the FITS-file on the screen using the <code>fdump</code> command. Here is the output of the latter, showing typical values of the keywords above:
<pre>
wilms@leo:~/isistut> fdump standard2f_0134off_top.pha
Name of optional output file[STDOUT]
Names of columns[]
Lists of rows[-]
SIMPLE = T / file does conform to FITS standard
BITPIX = -32 / number of bits per data pixel
NAXIS = 0 / number of data axes
EXTEND = T / FITS dataset may contain extensions
COMMENT FITS (Flexible Image Transport System) format is defined in 'Astronomy
COMMENT and Astrophysics', volume 376, page 359; bibcode: 2001A&A...376..359H
:
: ... many further lines
:
XTENSION= 'BINTABLE' / binary table extension
BITPIX = 8 / 8-bit bytes
:
:
EXTNAME = 'SPECTRUM' / name of this binary table extension
:
TELESCOP= 'XTE ' / Telescope (mission) name
INSTRUME= 'PCA ' / Instrument name
FILTER = 'NONE ' / Instrument filter in use
EXPOSURE= 2.52800000000001E+03 / Exposure time
:
BACKFILE= 'standard2f_back_SkyVLE_top_good_0134off.pha' / Background FITS file f
CORRFILE= 'standard2f_back_SkyVLE_top_good_0134off.pha' / Correlation FITS file
RESPFILE= 'p2_LR1_2010-07-04.rsp' / Redistribution matrix file (RMF)
ANCRFILE= 'NONE ' / Ancillary response file (ARF)
:
CREATOR = 'SAEXTRCT version 4.2g' / Program name that produced this file
DATE = '2011-06-26T10:08:03' / file creation date (YYYY-MM-DDThh:mm:ss UT)
RA_OBJ = 2.99591705E+02 / RA of First input object
DEC_OBJ = 3.52016983E+01 / DEC of First input object
EQUINOX = 2000.00 / Equinox of the FIRST object
:
DATASUM = '3317156129' / data unit checksum updated 2011-06-26T10:08:03
END

CHANNEL COUNTS STAT_ERR
count count
1 0 2.860600000000000E+04 1.691330836944682E+02
</pre>
The data themselves give, for each PHA-channel, the number of counts measured in the <code>COUNTS</code> column and the uncertainty of the data in the <code>STAT_ERR</code> column. If the data have not been background subtracted before the analysis, which is typical for most instruments except for data from coded mask telescopes, then <code>STAT_ERR</code> will usually have been determined assuming Poisson-statistics, i.e., it is the square-root of the value in <code>COUNTS</code>.

There are many more useful programs to inspect FITS-files. You can get an overview of what is available using
<pre>
wilms@leo:~/isistut> fhelp ftools
</pre>
and if you only want to see the list of general (non satellite-specific) tools
<pre>
wilms@leo:~/isistut> fhelp futils
</pre>
Full information on individual ftools can be obtained with <code>fhelp toolname</code>, e.g.,
<pre>
wilms@leo:~/isistut> fhelp fdump
</pre>
Other useful tools for inspecting FITS-files are, e.g., <code>fstruct</code> and <code>fstatistic</code>.

'''''Exercise 1'''''
# For your example data set, determine the date of the observation, the exposure time, and the name of the background file.
# Use <code>fstruct</code> to determine the structure of the backgrund file and confirm that it is the same as the structure of the PHA file containing the data.

=== Invoking isis ===

Isis is a command-line program and is therefore usually executed from the command line (the details are explained in the installation instructions):
<pre>
wilms@leo:~> isis
</pre>
which then prints out some start up messages before you end with the isis prompt:
<pre>
Welcome to ISIS Version 1.6.2-44
Copyright (C) 1998-2020 Massachusetts Institute of Technology

Isis web page: http://space.mit.edu/cxc/isis/
Mailing list archive: http://space.mit.edu/cxc/isis/archive/
Send questions to the mailing list: <isis-users@space.mit.edu>.
For a summary of recent changes, type: "help changes"

isis>
</pre>
As part of its startup, isis executes a file called [[ISIS auto start (.isisrc)|.isisrc]], which is useful for setting up a standard environment.

In the following we will show you an interactive session with isis. It is the typical approach when working with new data to look at these first by hand, in a way similar to that shown here. In later, more advanced analysis you will probably mainly interact with isis through programs, although it should be emphasized that working interactively with data first is always a good idea. This is the only way how you can get a good feeling for your data, even though automated reductions ''are'' important, especially when working on data sets with many different observations.

For a more formal walk through through isis and the programming language s-lang, take a look at the [http://space.mit.edu/cxc/isis isis web page], especially the [https://space.mit.edu/cxc/isis/docs.html documentation] available there.

=== Loading and Inspecting Your Data Set ===

We now load the data we looked at before into isis:
<pre>
pca=load_data("standard2f_0134off_top.pha");
</pre>
The <code>load_data</code> command loads the file given as its argument and returns an unique number that identifies this data set. In the above example, this identifier is stored in the variable called <code>pca</code> (it usually makes sense to use the name of the detector with which the data were taken, although there are exceptions). Note that the command ends with a semicolon. This is standard in slang, the language on which isis is based. Although it is in principle possible to switch off this feature when working interactively with isis<ref>since you are curious: put<pre>Isis_Append_Semicolon=1;</pre> in your <code>~/.isisrc</code></ref>, we recommend you do not use this option -- having to type the semicolon requires you to think before doing something, which is generally a good idea ;-).

If all goes fine, you will be informed that the response matrix includes the ARF. Now check whether isis loaded what you think it should have loaded by looking at some basic information about the background file, the RMF, and the ARF:
<pre>
isis> list_data;
Current Spectrum List:
id instrument part/m src use/nbins A R totcts exp(ksec) target
1 PCA 0 129/ 129 - 1 3.1773e+06 2.528 CYG_X-1
file: standard2f_0134off_top.pha
back: standard2f_back_SkyVLE_top_good_0134off.pha
</pre>
Amongs others, the table columns include
* <code>id</code>: the identifier of this data set,
* <code>nbins</code>: the number of spectral bins,
* <code>totcts</code>: the total counts in the spectrum,
* <code>exp</code>: the exposure time in kiloseconds, and
* <code>target</code>: the nominal source we are working with.
Finally, the output also lists the file name and the associated background file.

Similar information can also be obtained for the response matrix and the ARF using the commands
<pre>
list_rmf;
list_arf;
</pre>
Note that for your data set no information is given back for the ARF, since none was loaded.

Like for all commands in isis, information about the commands can be obtained with
<pre>
isis> help commandname
</pre>
so, for example,
<pre>
isis> help list_arf
</pre>
(If this does not give you help for the command you put in, you can try just
<pre>
isis> commandname;
</pre> without any additional arguments. For some commands that works.)
Some of the help information might appear pure gibberish for you. Ignore this for the moment, with time it will all become clear to you.

A second help function that is very useful is the <code>apropos</code> command. For example, if you want to do something with an ARF, do
<pre>
isis> apropos arf
</pre>
which will return all isis commands that contain "arf" in their name.

'''''Exercise 2'''''
# Load your data set and check that the information given by ISIS using the above commands is identical to the information that you obtained in the previous exercise.

=== Plotting the Data ===

X-ray data analysis of a data set that you do not yet know consists basically of the following steps:
# plot something
# think about what the plot/data set tries to tell you
# try something out (e.g., perform a fit)
# goto 1
and then repeat until you are convinced that everything works as expected. Depending on the data set, the above might take five minutes, but we also had complicated data sets that so far have resulted in 2-3 PhD theses...

Therefore, as the first step, we take a look at our data.

While isis contains some basic plotting routines, it is generally faster to use the very powerful plotting routines developed at MIT and at Remeis/ECAP to look at the data. The reason is that these are more user friendly than the basic isis routines.

In order to do so, we first need to load the Remeis isis scripts. In our standard install, just do a
<pre>
isis> require("isisscripts");
</pre>
The <code>isisscripts</code> are a large set of useful routines developed by many people. If you use them for professional work, please contact J. Wilms first and ask whom to put in the acknowledgments of your paper. They are freely available through a git-repository.

So let's plot the data set:
<pre>
isis> plot_counts(pca);
</pre>
A window pops up, looking something like this

[[File:Walkthrough01.png|center]]

In this standard display, not much can be seen except for the fact that the detector sensitivity is the best at low energies. For this reason, we first switch the plot over to a log-log plot and plot again:
<pre>
isis> xlog;
isis> ylog;
isis> plot_counts(pca);
</pre>
This results in a much nicer plot. With the exception of gratings data, it is usually better to take a look at X-ray data in log-log space, so you should get used to switching over to log-space before doing any plots:

[[File:Walkthrough02.png|center]]

Note that what is shown are counts per PHA bin as a function of energy. Here, the response matrix is used to get an approximate conversion of the channel number to energy. The jump at around 20keV is not a spectral feature, but caused by the detector: at this energy, the standard data mode on RXTE PCA increases the energy width per PHA bin by a factor of two. Since the spectrum changes only slowly at this energy, because of the increase in width twice as many counts are detected in this bin. In addition, the feature at around 30keV is also a detector feature, it mainly reflects the change in sensitivity of this Xe-based proportional counter at the Xe-K-edge, which is at roughly 30keV.

Experience for this detector shows that its calibration is best at energies between 3keV and 22keV, such that for the moment we will ignore what is happening outside of this energy band using isis' <code>notice</code> function:
<pre>
isis> notice_values(pca,3.,22.;unit="keV");
isis> plot_counts(pca);
</pre>
Note that immediately after ignoring, we plot the data again in order to make sure that our command worked as intended. This way you can visually confirm, e.g., that a feature that you want to ignore really was outside of the energy range considered. Furthermore, note that we are explicitly telling isis to work in energy space. This is necessary since for historic reasons many isis commands are by default working in wavelength space.

Other useful isis commands for noticing and ignoring energy and wavelength ranges are
<pre>
ignore(id); % Ignore dataset id
notice(id,a,b); % Notice wavelength range [a,b] in dataset id
notice_en(id,a,b); % Notice energy range [a,b] in dataset id
xnotice(id,a,b); % *Only* notice wavelength range [a,b] in dataset id
xnotice_en(id,a,b); % *Only* notice energy range [a,b] in dataset id
exclude(id); % Don't change the ignored/noticed channels, but
% exclude the whole data set until reinstated with:
include(id); % Reinstate the data with prior excluded channels
</pre>
You can get more information about all of these commands with the <code>.help</code>-command. Note that all of the above commands are "inclusive", in the sense that the energy bins in the spectrum that include the two borders, a and b, are contained in the noticed energy band.

'''''Exercise 3'''''
# Perform the above steps for your data set. In the write up of your homework, include the relevant figures. Prepare these figures as publication-quality (postscript) figures. For this you will have to switch the output to postscript before plotting, and switch back to screen output afterwards:
<pre>isis>plotid = open_print("example.ps/vcps");
isis> keynote_size; nice_width;
isis> plot_counts(pca);
isis> close_print(plotid);
</pre> where <code>example.ps</code> is the file name of the postscript file, and where <code>keynote_size</code> and <code>nice_width</code> set the size of the figure to something that is appropriate for inclusion into a journal article. If you rather work with pdf, convert the ps-file to pdf afterwards, e.g., using Linux <code>epstopdf</code> program.

=== Inspecting ARF and RMF ===

It is always useful in data analysis to have a feeling for the major features introduced by specific properties of the detector used to measure the data. For example, in the spectra above there are drops in detector sensitivity at the K- and L-edges of the detector gas. Usually, the regions around these edges are less well calibrated. Visualizing the ARF and RMF helps in this case (as does reading the user's manual for the satellite you're using...).

It is easy to produce a plot of the RMF:
<pre>
isis> fits_plot_rmf("p2_LR1_2009-05-06.rsp");
</pre>

The resulting plot should be similar to this:

[[File:Rmf.png|center]]

To visualize the sensitivity of the detector we need to plot the effective area of the detector as a function of energy. Depending on the instrument, the detector sensitivity is either saved as a separate ARF (Ancilliary Response File) or it is stored as part of the RMF. In the latter case isis will tell you so with the warning message "RMF includes the effective area" when you load the response. In this case we need to factor the response first:
<pre>
isis> rsp=load_rmf("p2_LR1_2009-05-06.rsp");
RMF includes the effective area
isis> arf=factor_rsp(rsp);
</pre>

We can then get the information about the effective area and plot it:
<pre>
isis> arfdata=get_arf(arf);
isis> xlog;
isis> hplot(_A(arfdata));
</pre>

where the function _A converts the wavelength information contained in the structure arfdata into keV.

[[File:Arf.gif|center]]

=== Performing a First Spectral Fit ===

We are now ready to perform a first spectral fit. We first need to define the spectral model that we want to describe our data with. In general, one first tries to get a rough description of the data, which is for example based on earlier observations of the object, and then refines this spectral model by adding further spectral components if an initial fit was successful. Isis includes a large number of spectral models. Since the models are derived from XSPEC, a good overview is given by the exhaustive list of the models in the [https://heasarc.gsfc.nasa.gov/xanadu/xspec/manual/XspecManual.html XSPEC manual].

What model to use depends on the object one looks at. In most cases, one tries either a power law or a black body first and only later works with more CPU-intensive, physics-based models. Since all X-ray sources are absorbed by the interstellar medium in our Galaxy, one ''always'' includes Galactic absorption.

Here, we know that Cygnus X-1 is a black hole. These often have power-law spectra. We therefore start by trying an absorbed power-law as our fit function:
<pre>
isis>fit_fun("tbabs(1)*powerlaw(1)");
</pre>
Notice the numbers behind the model components. These will be later used to distinguish different fit-functions, e.g., when one works with a source that has a spectrum that can be described as the sum of two power laws of different photon indices.

Next we take a look at our fit parameters:
<pre>
isis> list_par;
tbabs(1)*powerlaw(1)
idx param tie-to freeze value min max
1 tbabs(1).nH 0 0 1 0 100000 10^22
2 powerlaw(1).norm 0 0 1 0 1e+10
3 powerlaw(1).PhoIndex 0 0 1 -2 9
</pre>
Amongst other information, which we will be discussing in a later tutorial, the table contains the following information:
* <code>idx</code>: The index of the parameter (see below)
* <code>param</code>: The name of the parameter. For example, <code>tbabs(1).nH</code> is the absorption column (in units of 10^22 cm-2. The physical meaning of the parameters is explained in the [https://heasarc.gsfc.nasa.gov/xanadu/xspec/manual/XspecManual.html XSPEC manual].
* <code>tie-to</code> and <code>freeze</code>: see later
* <code>value</code>: the current value of the parameter
* <code>min</code> and <code>max</code>: The fit has to remain in the range between these two values.

Before we do our first fit, we take a look at how this model looks like when folded through the detector response matrix. In order to do so we first ask isis to change the model flux such that the predicted count rate is close to the model count rate.
<pre>
isis> renorm_counts;
tbvabs Version 1.0
Cosmic absorption with grains and H2
Wilms, Allen, & McCray 2000
Questions: Adrienne Allen or Joern Wilms
allenu@super.colorado.edu
wilms@astro.uni-tuebingen.de
Parameters[Variable] = 3[1]
Data bins = 45
Chi-square = 898942.6
Reduced chi-square = 20430.51
0
</pre>
Isis has changed the parameter <code>powerlaw(1).norm</code> and has left all other parameters unchanged:
<pre>
isis> list_par;
tbabs(1)*powerlaw(1)
idx param tie-to freeze value min max
1 tbabs(1).nH 0 0 1 0 100000 10^22
2 powerlaw(1).norm 0 0 0.4145608 0 1e+10
3 powerlaw(1).PhoIndex 0 0 1 -2 9
</pre>
Now let us take a look at what the model looks like
<pre>
isis> plot_counts(pca);
</pre>
The resulting plot looks something like this:

[[File:Walkthrough03.png|center]]

Notice that the slope of the spectrum and the data is very different. With a photon index of 1 the spectrum is harder than the data. We therefore change the photon index to something that is more typical for black holes, renorm the spectrum and plot it again:
<pre>
isis> set_par(3,1.7);
isis> renorm_counts;
Parameters[Variable] = 3[1]
Data bins = 45
Chi-square = 339671.5
Reduced chi-square = 7719.808
0
isis> plot_counts(pca);
</pre>
The resulting model looks like this:

[[File:Walkthrough04.png|center]]

Note that the overall slope now looks ok, but there is still some deviation between the data and the model at the soft part of the spectrum, where the model looks too much absorbed. Taking a look at the isis help for <code>set_par</code>, we are being told that instead of changing the parameter by giving <code>set_par</code> its index number, we could also have given the full name of the parameter. So let us remove some absorption to get the curvature at the low energies right, by setting NH to its interstellar value of <latex>N_\mathrm{H}=3\times 10^{21}\,\mathrm{cm}^{-2}</latex>.
<pre>
isis> set_par("tbabs(1).nH",0.3);
isis> renorm_counts;
Parameters[Variable] = 3[1]
Data bins = 45
Chi-square = 314595.1
Reduced chi-square = 7149.888
0
isis> plot_counts(pca);
</pre>
Note that the Chi-square value decreased, meaning that the new description of the model is slightly better than the previous one.

We now have starting values that are good enough to start the proper fitting. Here isis is using a so-called Levenberg-Marquardt-gradient method to minimize chi-square by varying the parameters. This is done step by step, until a (possibly local) minimum is reached. In order to see how the parameters are being varied, we instruct isis to display all intermediate parameter values first, and then perform the fit:
<pre>
isis> Fit_Verbose=1;
isis> fit_counts();
chisqr= 3.1460e+05:
tbabs(1).nH= 3.00000000e-01 powerlaw(1).norm= 2.26407499e+00
powerlaw(1).PhoIndex= 1.70000000e+00
chisqr= 3.1460e+05:
tbabs(1).nH= 3.00030000e-01 powerlaw(1).norm= 2.26407499e+00
powerlaw(1).PhoIndex= 1.70000000e+00
:
: multiple further steps
:
chisqr= 9.6239e+03:
tbabs(1).nH= 0.00000000e+00 powerlaw(1).norm= 1.32707632e+01
powerlaw(1).PhoIndex= 2.61135748e+00
chi-square value converged
Parameters[Variable] = 3[3]
Data bins = 45
Chi-square = 9623.869
Reduced chi-square = 229.1397
0
</pre>
While the reduced chi-square is already much smaller, it is still very much above its ideal value of around unity. Let us take a look what the current best fit looks like by plotting it again:

[[File:Walkthrough05.png|center]]

The model describes the overall shape of the data rather well, but statistically significant residuals remain. We will tackle these in the next section, but first let us save our work so far such that we can start again from the current best fit in case our next steps are not successful:
<pre>
isis> save_par("powerlaw.par");
</pre>
This creates a file called <code>powerlaw.par</code> that can be re-read later using
<pre>
isis> load_par("powerlaw.par");
</pre>
The file is a simple ASCII file that you can either just display on screen (using the unix-command <code>cat powerlaw.par</code> from the shell or any editor of your choice.

'''''Exercise 4'''''
# Perform the procedure described above with "your" data set, documenting all steps.
# If you want to change more than one parameter at a time, instead of using <code>set_par</code> you can also use the <code>edit_par</code> function, which will invoke an editor of your choice with a table like the parameter table above. You can then overwrite all values with your new values, save this temporary file, and exit the editor. Try this with your data set.

=== Improving the Initial Fit ===

Now that we have an initial fit, we can take a closer look at the difference between the data and the model to get a feeling what we can do to improve the model. Since the data values and the model are already rather close together, guessing what is going on by looking at the slight differences between both is not very useful. We therefore plot our data again, but this time not only displaying the data but also the "residuals", that is the difference between the data and the model:
<pre>
isis> plot_data(pca;res=1);
</pre>
This results in the following figure:

[[File:Walkthrough06.png|center]]

Note the following:
* instead of using <code>plot_counts</code> we have used <code>plot_data</code> (which is in reality an alias for the <code>plot_data_counts</code> function). <code>plot_data</code> displays the counts and the model in terms of counts per keV, while previously we used counts per PHA bin. This is the preferred way to plot X-ray data, since it is slightly closer to showing the proper spectrum than <code>plot_counts</code>.
* Secondly, in addition to plotting the data we are also plotting the residuals, by using the "qualifier" <code>res=1</code>. In Slang/isis, qualifiers are special switches in functions. They all have names (<code>res</code> in the above example), i.e., the order in which they are listed after the initial semicolon does not matter. The most important ways of displaying residuals are
** <code>res=1</code>: Display the residual in terms of chi, i.e., display the value of <latex>(data-model)/\sigma</latex> where <latex>\sigma</latex> is the statistical uncertainty of the bin.
** <code>res=3</code>: Display the ratio between the data and the model, <latex>data/model</latex>.
* other qualifiers that are useful in plotting are:
** <code>mcol=number</code>: the color of the model, number is, well, a number. Avoid <code>mcol=3</code> and <code>mcol=5</code> since these colors do not show up on beamers.
** <code>dcol=number</code>: dito, for the data
** <code>decol=number</code>: dito, for the error bars
** <code>bkg</code>: if <code>bkg=0</code> then plot the data with the background subtracted, if <code>bkg=1</code> also show the background (this will be useful later).
** <code>xrange={min,max}</code>: plot the x-axis from min to max only. Note the curly braces! Set <code>min</code> and/or <code>max</code> to <code>NULL</code> if you want to reset this range to its default value. It is important to remember that <code>xrange</code> just sets the ''plot''-range, you need to use <code>notice</code> to set the energy range that is used for fitting.
** <code>yrange={min,max}</code>: dito, for the y-axis.

As an example, try
<pre>
isis> plot_data(pca;res=1,mcol=2,dcol=1,decol=5);
</pre>

The residuals in the plot tell us two things:
- there is a "bump" around 6.4keV. This is typically an indication that there is an iron Kα line present around 6.4keV.
- there is a "soft excess" at low energies, which might be indicative of an accretion disk.

Looking at the [https://heasarc.gsfc.nasa.gov/xanadu/xspec/manual/XspecManual.html XSPEC] manual tells us that accretion disk spectra are modeled with the <code>diskbb</code> model while emission lines are modeled using the <code>gauss</code> model. However, reading the isis manual tells us that the ''only'' model that has a different name in isis and in XSPEC is <code>gauss</code> where we will have to use <code>egauss</code> instead.

Based with this information we setup the new fit function as follows
<pre>
isis> fit_fun("tbabs(1)*(diskbb(1)+egauss(1)+powerlaw(1))");
</pre>
and identify the new parameters with <code>list_par</code>:
<pre>

isis> list_par;
tbabs(1)*(diskbb(1)+egauss(1)+powerlaw(1))
idx param tie-to freeze value min max
1 tbabs(1).nH 0 0 0 0 100000 10^22
2 diskbb(1).norm 0 0 1 0 1e+10
3 diskbb(1).Tin 0 0 1 0 1000 keV
4 egauss(1).area 0 0 1 0 0 photons/s/cm^2
5 egauss(1).center 0 0 1 0 0 keV
6 egauss(1).sigma 0 0 0.002 1e-06 1 keV
7 powerlaw(1).norm 0 0 13.27076 0 1e+10
8 powerlaw(1).PhoIndex 0 0 2.611357 -2 9
</pre>
We then set the center of the Gaussian to 6.4keV (<code>set_par(5,6.4);</code>) and plot again. Nothing changes. The reason is that we first have to tell isis to recalculate the model. Not doing this automatically after every invocation of <code>set_par</code> makes sense since some models might take up large amounts of CPU time. To recalculate the model, use
<pre>
isis> eval_counts;
</pre>
Plot the model again (using <code>plot_data</code>). You will notice that the Fe line is too strong. Reduce its flux accordingly by changing the <code>area</code> parameter. You will probably need a few attempts to get something that looks ok. Then repeat this procedure with the parameters of the accretion disk until you get something that looks halfway ok. Save this attempt, just to be on the save side, and then perform a fit.

Repeating the above a few times, I managed to coax the following best fit out of the data
<pre>
isis> list_par;
tbabs(1)*(diskbb(1)+egauss(1)+powerlaw(1))
idx param tie-to freeze value min max
1 tbabs(1).nH 0 0 0 0 100000 10^22
2 diskbb(1).norm 0 0 4088.32 0 1e+10
3 diskbb(1).Tin 0 0 0.7163385 0 1000 keV
4 egauss(1).area 0 0 0.07462147 0 0 photons/s/cm^2
5 egauss(1).center 0 0 6.085836 0 0 keV
6 egauss(1).sigma 0 0 1 1e-06 1 keV
7 powerlaw(1).norm 0 0 2.948465 0 1e+10
8 powerlaw(1).PhoIndex 0 0 1.984697 -2 9
</pre>
with
<pre>
Parameters[Variable] = 8[8]
Data bins = 45
Chi-square = 291.7067
Reduced chi-square = 7.883964
</pre>
This fit looks the following:

[[File:Walkthrough07.png|center]]

This is quite ok for such a simple model. Note that there still is some hardening above 10keV and the residuals are not perfect around 8keV either. This is due to the too large width of the simple Gaussian line, limitations in the <code>diskbb</code>-model, and the fact that in this data set the source was in its intermediate state, where the combination of the disk component and the power law is notoriously hard to model.

'''''Exercise 5'''''
# you guessed it: try to find a good fit for your data set.

=== References ===
[[Category:Isis / Slang]]

Isis tutorial installing

2020-05-19T13:06:15Z

Wilms: revision 2020

====Getting ISIS====
Installing ISIS and all the modules it depends on, is not a trivial task.

We therefore provide a complete isis environment that is pre-installed in a so-called [https://sylabs.io/guides/3.5/user-guide/# singularity environment]. Singularity runs very well under Linux and can also be installed under windows, although this is a bit more complex, which is why we also offer an alternative. Note that you will need about 4 GB of disk space for the installation.

If you do not have enough disk space available or if you are not happy/comfortable with installing software on your computer, we also have an option to run the tutorials on machines at the observatory.

=====Setup for Linux =====
* Install singularity. How you do this depends on the flavor of Linux that you have installed. On ubuntu systems, this is as easy as executing

sudo apt-get install singularity-container

On other Linux versions different commands are required.

* Create a working directory for the lecture and download the singularity image for isis and the other tools required for the tutorial from https://www.sternwarte.uni-erlangen.de/isis/isis-singularity.img , e.g.,

mkdir xray
cd xray
wget https://www.sternwarte.uni-erlangen.de/isis/isis-singularity.img

* you can then launch the singularity environment as follows:
cd xray
singularity run isis-singularity.img

This brings you into an environment that contains most of the relevant X-ray astronomical software, such as, e.g., fv (which you might want to use to display X-ray astronomical data files). You then launch isis by typing '''isis''':

isis

=====Setup for Windows =====

* Install singularity using the instructions [https://sylabs.io/guides/3.5/user-guide/# on the singularity homepage]. This is a somewhat involved process, but doable in principle if you are ok with computers. If the instructions don't

* Follow the instructions above.

(an alternative is currently being prepared - watch this place)

=====Working on Remeis observatory computers=====

* If you do not have enough disk space on your computer or do not want to install things locally, contact Ingo Kreykenbohm at the email address given out in the lecture and ask him to create an account on the Remeis computers for you.

* To work on the computers from home, once you have the Remeis account, install the X2go remote desktop environment, following [https://www.sternwarte.uni-erlangen.de/wiki/index.php/X2Go_Remote_Desktop the instructions here].

[[Category:Isis / Slang]]

Remeis English Checklist

2019-07-01T19:29:12Z

Wilms: /* The Remeis English Checklist */

====== The Remeis English Checklist ======

(by J. Wilms and K. Pottschmidt)

'''''First of all and most importantly:'''''

* did you read the instructions to authors of the journal? If you are working on a thesis, did you read those of [http://www.aanda.org/doc_journal/instructions/aadoc.pdf Astronomy and Astrophysics]?
* did you read appendix A of the [https://journals.aps.org/files/rmpguide.pdf instructions to authors] of Rev Mod Phys?

==== Punctuation ====

* did you remove all commas before "that"?
* did you end your footnotes and captions with a full stop (".")?
* did you make sure that your use of "data" is correct and uses plural verbs?
* did you make sure that you do not have a ":" anywhere before an equation, but that your equations are seen as part of your sentences?
* did you make sure that you have commas surrounding "i.e." and "e.g."?

==== Spelling and Word usage ====

* do you consistently use either British or American spelling?
* did you run a spell checker over your manuscript? For TeX, use "ispell" or the built in spell checker in emacs.
* did you make sure not to use country prefixes in addresses in the author list?
* did you avoid passive voice as much as possible?
* did you make sure that you are //not// using "The found results are..." and similar German constructs in your text?
* did you make sure that everything in your text that is not your original result is accompanied by proper citations?
* did you make sure that you distinguish between "estimate" and "estimation" by replacing all "estimation" with "estimate"?
* did you replace all uses of "exemplary" by "example"?
* did you replace all uses of "the actual value" by "the real value"? (if you are German, "actual" does not mean "aktuell"!)
* did you remove all uses of "hence" and "thereby"?
* did you make sure that you use "however" as sparingly as possible?
* did you make sure that you did not use "the equation reads..", but rather used "the equation is..." or "the equation is given by..."?
* did you avoid split infinitives? ("to boldly go..." is wrong; yes, in many cases split infinitives are ok in current English, but they tend to be so often used wrongly by non-native speakers that it is best to avoid them)
* did you make sure that you distinguish properly between "this" and "these"?
* did you make use of the "Oxford comma", i.e., do you have a comma before "and" in lists?
* did you use "i.e." and "e.g." correctly, i.e., using "i.e." for a specific clarification or definition and "e.g." where you would otherwise use "for example"?
* did you use the IAU recommended year - month - day sequences (2016 March 15)?
* did you make sure that you did not use contractions such as "didn't" or "you're"?
* did you replace "cf." with "see" everywhere since you know that "cf." means "compare"?
* did you make sure that the reader will understand what thing you refer to when using "it" rather than naming it?
* did you make sure that all uses of "this" are followed by the object you are referring to?
* did you use "led" rather than "lead" when using the past tense of the verb "to lead"?
* did you reread the manuscript for internal consistency after you added comments from your coauthors?
* did you make sure that your sentences are short (rule of thumb: if a sentence goes over more than three lines it is probably too long)?
* did you check that you did not combine two sentences that could be separate sentences with "and"?
* did you avoid abbreviations as much as possible and only used them when they are really, really common (HST, AGN, XMM,...)?
* did you check that you defined all abbreviations that you used at their first usage? ("...Active Galactic Nucleus (AGN)..." //not// "...AGN (Active Galactic Nucleus)..." )

==== Citations ====

* did you add the journal to all publications where you list the arXiv-reference and not just blindly copy the erroneous ADS bibtex entry?
* did you make sure that you distinguished between arXiv references where a paper is submitted and references where a paper is already accepted by checking the paper author's comment on the arXiv-page for that article?
* did you remove the page number for all ATEL-references downloaded from ADS and changed the journal name to "Astron. Tel." or "ATEL"? (and similar for IAU telegrams)
* did you add editors and the title of the conference publication to all conference publications?
* did you add the publisher and place information (city only) to all books, conference publications, and other book-like publications that you are citing?
* did you check that your references are correct in that you are using ''\citet{biblabel}'' for references in the text and ''\citep{biblabel}'' for references in parentheses?
* did you make sure that none of your ''\citet{..}'' commands refer to more than one biblabel?

==== Typesetting (mainly in TeX) ====

* did you check for missing spaces between values and units?
* did you make sure that all scientific units are typeset in <code>\mathrm</code>?
* did you make sure not to use constructs such as <code>$\mathrm{m}/\mathrm{s}$</code> by using <code>$\mathrm{m}\,\mathrm{s}^{-1}$</code> instead?
* did you make sure that almost all of your error bars are rounded up to only one significant digit rather than following the DIN-norm (which is not applied in astronomical journals)?
* did you make sure that you are not using any positioning commands for the table or figure environment such as <code>\begin{table}[htpb]</code>?
* did you make sure that your tables have captions above the table, and figures have captions below the figure or next to it (where allowed by the style)?
* did you make sure that you use empty lines to denote the start of a new paragraph rather than the ''\\''-command? (use <code>\parindent{0pt}</code> if you do not want to indent paragraphs)
* did you make sure that there are no paragraph endings above or below <code>\begin{equation}...\end{equation}</code> by ensuring that there is no empty line above or below the ''equation''-environment?
* did you make sure that you are not using <code>$\frac{a}{b}$</code> in normal text, but use <code>$a/b$</code> instead?
* did you make sure that you are not using the <code>displaymath</code>-environment and that all equations are numbered?
* did you make sure that all of your sections, subsections, paragraphs and so on are numbered?
* did you avoid any and all uses of <code>\bf</code>, <code>\it</code>, <code>\sl</code>, or <code>\em</code> and use the proper commands <code>\textbf</code>, <code>\textit</code>, <code>\textsl</code>, and <code>\emph</code> instead?
* did you use the en-dash of TeX for ranges, even if they occur in math, by using <code>--</code> in text mode rather than a minus sign? (that is, did you typeset a range in an equation as <code>$3x$--$5x$</code> or <code>$3x\mbox{--}5x$</code> rather than, erroneously, <code>$3x-5x$</code>?
* did you correctly use the minus-sign and dashes in astronomical source names, where the name contains coordinates and the <q>dash</q> really is a southern declination or Galactic latitude, that is, did you typeset <code>Her X-1</code>, <code>LMC X-3</code>, but <code>GX\,339$-$4</code> or <code>IGR J16318$-$4848</code> (and as a really difficult one: <code>MCG$-$6-30-15</code>)?

[[Category:Current Members]]

Remeis English Checklist

2019-07-01T19:27:43Z

Wilms: /* Typesetting (mainly in TeX) */

====== The Remeis English Checklist ======

(by J. Wilms and K. Pottschmidt)

''First of all and most importantly:''

* did you read the instructions to authors of the journal? If you are working on a thesis, did you read those of [http://www.aanda.org/doc_journal/instructions/aadoc.pdf Astronomy and Astrophysics]?
* did you read appendix A of the [https://journals.aps.org/files/rmpguide.pdf instructions to authors] of Rev Mod Phys?

==== Punctuation ====

* did you remove all commas before "that"?
* did you end your footnotes and captions with a full stop (".")?
* did you make sure that your use of "data" is correct and uses plural verbs?
* did you make sure that you do not have a ":" anywhere before an equation, but that your equations are seen as part of your sentences?
* did you make sure that you have commas surrounding "i.e." and "e.g."?

==== Spelling and Word usage ====

* do you consistently use either British or American spelling?
* did you run a spell checker over your manuscript? For TeX, use "ispell" or the built in spell checker in emacs.
* did you make sure not to use country prefixes in addresses in the author list?
* did you avoid passive voice as much as possible?
* did you make sure that you are //not// using "The found results are..." and similar German constructs in your text?
* did you make sure that everything in your text that is not your original result is accompanied by proper citations?
* did you make sure that you distinguish between "estimate" and "estimation" by replacing all "estimation" with "estimate"?
* did you replace all uses of "exemplary" by "example"?
* did you replace all uses of "the actual value" by "the real value"? (if you are German, "actual" does not mean "aktuell"!)
* did you remove all uses of "hence" and "thereby"?
* did you make sure that you use "however" as sparingly as possible?
* did you make sure that you did not use "the equation reads..", but rather used "the equation is..." or "the equation is given by..."?
* did you avoid split infinitives? ("to boldly go..." is wrong; yes, in many cases split infinitives are ok in current English, but they tend to be so often used wrongly by non-native speakers that it is best to avoid them)
* did you make sure that you distinguish properly between "this" and "these"?
* did you make use of the "Oxford comma", i.e., do you have a comma before "and" in lists?
* did you use "i.e." and "e.g." correctly, i.e., using "i.e." for a specific clarification or definition and "e.g." where you would otherwise use "for example"?
* did you use the IAU recommended year - month - day sequences (2016 March 15)?
* did you make sure that you did not use contractions such as "didn't" or "you're"?
* did you replace "cf." with "see" everywhere since you know that "cf." means "compare"?
* did you make sure that the reader will understand what thing you refer to when using "it" rather than naming it?
* did you make sure that all uses of "this" are followed by the object you are referring to?
* did you use "led" rather than "lead" when using the past tense of the verb "to lead"?
* did you reread the manuscript for internal consistency after you added comments from your coauthors?
* did you make sure that your sentences are short (rule of thumb: if a sentence goes over more than three lines it is probably too long)?
* did you check that you did not combine two sentences that could be separate sentences with "and"?
* did you avoid abbreviations as much as possible and only used them when they are really, really common (HST, AGN, XMM,...)?
* did you check that you defined all abbreviations that you used at their first usage? ("...Active Galactic Nucleus (AGN)..." //not// "...AGN (Active Galactic Nucleus)..." )

==== Citations ====

* did you add the journal to all publications where you list the arXiv-reference and not just blindly copy the erroneous ADS bibtex entry?
* did you make sure that you distinguished between arXiv references where a paper is submitted and references where a paper is already accepted by checking the paper author's comment on the arXiv-page for that article?
* did you remove the page number for all ATEL-references downloaded from ADS and changed the journal name to "Astron. Tel." or "ATEL"? (and similar for IAU telegrams)
* did you add editors and the title of the conference publication to all conference publications?
* did you add the publisher and place information (city only) to all books, conference publications, and other book-like publications that you are citing?
* did you check that your references are correct in that you are using ''\citet{biblabel}'' for references in the text and ''\citep{biblabel}'' for references in parentheses?
* did you make sure that none of your ''\citet{..}'' commands refer to more than one biblabel?

==== Typesetting (mainly in TeX) ====

* did you check for missing spaces between values and units?
* did you make sure that all scientific units are typeset in <code>\mathrm</code>?
* did you make sure not to use constructs such as <code>$\mathrm{m}/\mathrm{s}$</code> by using <code>$\mathrm{m}\,\mathrm{s}^{-1}$</code> instead?
* did you make sure that almost all of your error bars are rounded up to only one significant digit rather than following the DIN-norm (which is not applied in astronomical journals)?
* did you make sure that you are not using any positioning commands for the table or figure environment such as <code>\begin{table}[htpb]</code>?
* did you make sure that your tables have captions above the table, and figures have captions below the figure or next to it (where allowed by the style)?
* did you make sure that you use empty lines to denote the start of a new paragraph rather than the ''\\''-command? (use <code>\parindent{0pt}</code> if you do not want to indent paragraphs)
* did you make sure that there are no paragraph endings above or below <code>\begin{equation}...\end{equation}</code> by ensuring that there is no empty line above or below the ''equation''-environment?
* did you make sure that you are not using <code>$\frac{a}{b}$</code> in normal text, but use <code>$a/b$</code> instead?
* did you make sure that you are not using the <code>displaymath</code>-environment and that all equations are numbered?
* did you make sure that all of your sections, subsections, paragraphs and so on are numbered?
* did you avoid any and all uses of <code>\bf</code>, <code>\it</code>, <code>\sl</code>, or <code>\em</code> and use the proper commands <code>\textbf</code>, <code>\textit</code>, <code>\textsl</code>, and <code>\emph</code> instead?
* did you use the en-dash of TeX for ranges, even if they occur in math, by using <code>--</code> in text mode rather than a minus sign? (that is, did you typeset a range in an equation as <code>$3x$--$5x$</code> or <code>$3x\mbox{--}5x$</code> rather than, erroneously, <code>$3x-5x$</code>?
* did you correctly use the minus-sign and dashes in astronomical source names, where the name contains coordinates and the <q>dash</q> really is a southern declination or Galactic latitude, that is, did you typeset <code>Her X-1</code>, <code>LMC X-3</code>, but <code>GX\,339$-$4</code> or <code>IGR J16318$-$4848</code> (and as a really difficult one: <code>MCG$-$6-30-15</code>)?

[[Category:Current Members]]

Remeis English Checklist

2019-07-01T19:26:34Z

Wilms: /* Typesetting (mainly in TeX) */

====== The Remeis English Checklist ======

(by J. Wilms and K. Pottschmidt)

''First of all and most importantly:''

* did you read the instructions to authors of the journal? If you are working on a thesis, did you read those of [http://www.aanda.org/doc_journal/instructions/aadoc.pdf Astronomy and Astrophysics]?
* did you read appendix A of the [https://journals.aps.org/files/rmpguide.pdf instructions to authors] of Rev Mod Phys?

==== Punctuation ====

* did you remove all commas before "that"?
* did you end your footnotes and captions with a full stop (".")?
* did you make sure that your use of "data" is correct and uses plural verbs?
* did you make sure that you do not have a ":" anywhere before an equation, but that your equations are seen as part of your sentences?
* did you make sure that you have commas surrounding "i.e." and "e.g."?

==== Spelling and Word usage ====

* do you consistently use either British or American spelling?
* did you run a spell checker over your manuscript? For TeX, use "ispell" or the built in spell checker in emacs.
* did you make sure not to use country prefixes in addresses in the author list?
* did you avoid passive voice as much as possible?
* did you make sure that you are //not// using "The found results are..." and similar German constructs in your text?
* did you make sure that everything in your text that is not your original result is accompanied by proper citations?
* did you make sure that you distinguish between "estimate" and "estimation" by replacing all "estimation" with "estimate"?
* did you replace all uses of "exemplary" by "example"?
* did you replace all uses of "the actual value" by "the real value"? (if you are German, "actual" does not mean "aktuell"!)
* did you remove all uses of "hence" and "thereby"?
* did you make sure that you use "however" as sparingly as possible?
* did you make sure that you did not use "the equation reads..", but rather used "the equation is..." or "the equation is given by..."?
* did you avoid split infinitives? ("to boldly go..." is wrong; yes, in many cases split infinitives are ok in current English, but they tend to be so often used wrongly by non-native speakers that it is best to avoid them)
* did you make sure that you distinguish properly between "this" and "these"?
* did you make use of the "Oxford comma", i.e., do you have a comma before "and" in lists?
* did you use "i.e." and "e.g." correctly, i.e., using "i.e." for a specific clarification or definition and "e.g." where you would otherwise use "for example"?
* did you use the IAU recommended year - month - day sequences (2016 March 15)?
* did you make sure that you did not use contractions such as "didn't" or "you're"?
* did you replace "cf." with "see" everywhere since you know that "cf." means "compare"?
* did you make sure that the reader will understand what thing you refer to when using "it" rather than naming it?
* did you make sure that all uses of "this" are followed by the object you are referring to?
* did you use "led" rather than "lead" when using the past tense of the verb "to lead"?
* did you reread the manuscript for internal consistency after you added comments from your coauthors?
* did you make sure that your sentences are short (rule of thumb: if a sentence goes over more than three lines it is probably too long)?
* did you check that you did not combine two sentences that could be separate sentences with "and"?
* did you avoid abbreviations as much as possible and only used them when they are really, really common (HST, AGN, XMM,...)?
* did you check that you defined all abbreviations that you used at their first usage? ("...Active Galactic Nucleus (AGN)..." //not// "...AGN (Active Galactic Nucleus)..." )

==== Citations ====

* did you add the journal to all publications where you list the arXiv-reference and not just blindly copy the erroneous ADS bibtex entry?
* did you make sure that you distinguished between arXiv references where a paper is submitted and references where a paper is already accepted by checking the paper author's comment on the arXiv-page for that article?
* did you remove the page number for all ATEL-references downloaded from ADS and changed the journal name to "Astron. Tel." or "ATEL"? (and similar for IAU telegrams)
* did you add editors and the title of the conference publication to all conference publications?
* did you add the publisher and place information (city only) to all books, conference publications, and other book-like publications that you are citing?
* did you check that your references are correct in that you are using ''\citet{biblabel}'' for references in the text and ''\citep{biblabel}'' for references in parentheses?
* did you make sure that none of your ''\citet{..}'' commands refer to more than one biblabel?

==== Typesetting (mainly in TeX) ====

* did you check for missing spaces between values and units?
* did you make sure that all scientific units are typeset in <code>\mathrm</code>?
* did you make sure not to use constructs such as <code>$\mathrm{m}/\mathrm{s}$</code> by using <code>$\mathrm{m}\,\mathrm{s}^{-1}$</code> instead?
* did you make sure that almost all of your error bars are rounded up to only one significant digit rather than following the DIN-norm (which is not applied in astronomical journals)?
* did you make sure that you are not using any positioning commands for the table or figure environment such as <code>\begin{table}[htpb]</code>?
* did you make sure that your tables have captions above the table, and figures have captions below the figure or next to it (where allowed by the style)?
* did you make sure that you use empty lines to denote the start of a new paragraph rather than the ''\\''-command? (use <code>\parindent{0pt}</code> if you do not want to indent paragraphs)
* did you make sure that there are no paragraph endings above or below <code>\begin{equation}...\end{equation}</code> by ensuring that there is no empty line above or below the ''equation''-environment?
* did you make sure that you are not using <code>$\frac{a}{b}$</code> in normal text, but use <code>$a/b$</code> instead?
* did you make sure that you are not using the <code>displaymath</code>-environment and that all equations are numbered?
* did you make sure that all of your sections, subsections, paragraphs and so on are numbered?
* did you avoid any and all uses of <code>\bf</code>, <code>\it</code>, <code>\sl</code>, or <code>\em</code> and use the proper commands <code>\textbf</code>, <code>\textit</code>, <code>\textsl</code>, and <code>\emph</code> instead?
* did you use the en-dash of TeX for ranges, even if they occur in math, by using <code>--</code> in text mode rather than a minus sign? (that is, did you typeset a range in an equation as <code>$3x$--$5x$</code> or <code>$3x\mbox{--}5x$</code> rather than, erroneously, <code>$3x-5x$</code>?
* did you correctly use the minus-sign and dashes in astronomical source names, where the name contains coordinates and the ``dash'' really is a southern declination or Galactic latitude, that is, did you typeset <code>Her X-1</code>, <code>LMC X-3</code>, but <code>GX\,339$-$4</code> or <code>IGR J16318$-$4848</code> (and as a really difficult one: <code>MCG$-$6-30-15</code>)?

[[Category:Current Members]]

Slurm

2018-09-01T02:02:18Z

Wilms: /* Submitting a job array */

[[Category:Slurm]]

= About =

In order to spread the workload of scientific computations on our compute nodes the resource manager SLURM is used.

From [https://slurm.schedmd.com/overview.html official SLURM website]:

''Slurm is an open source, fault-tolerant, and highly scalable cluster management and job scheduling system for large and small Linux clusters. Slurm requires no kernel modifications for its operation and is relatively self-contained. As a cluster workload manager, Slurm has three key functions. First, it allocates exclusive and/or non-exclusive access to resources (compute nodes) to users for some duration of time so they can perform work. Second, it provides a framework for starting, executing, and monitoring work (normally a parallel job) on the set of allocated nodes. Finally, it arbitrates contention for resources by managing a queue of pending work.''
[[File:entities_slurm.gif|frame|Different entities of Slurm]]
From [https://slurm.schedmd.com/overview.html official SLURM website]:

''SLURM manages the cluster in partitions, which are a set of compute nodes. Note, that partitions may overlap, e.g. one compute node may be in two or more partitions. A node is a physical computer which provides consumable resources: CPUs and Memory. A CPU does not necessarily have to be a physical processor but is more like a virtual CPU to run one single task on. A dual core with hyper threading technology, for instance, would show up as a node with 4 CPUs consisting of two cores with the capability of running two threads on each core. Physical memory is defined in MB.''

The following partitions exist in the current setup:

* remeis: default partition, all machines, timelimit: 14days
* erosita: only available for selected people involved in the project, timelimit: infinite
* power: only the newest machines and servers, higher priority than 'remeis' (e.g. if you submit via power you will get the power machines as soon as possible and not compete with 'remeis' jobs but only other jobs submitted to 'power'), timelimit: 1day
* messier: only messier cluster, also higher priority than 'remeis', timelimit: 7 days
* debug: very high priority partition for software development, timelimit: 1h

= Quick users tutorial =

This tutorial will give you a quick overview over the most important commands. The [https://slurm.schedmd.com/overview.html official SLURM website] provides more detailed information.

== Get cluster status ==
In order to get an overview of the cluster, type
<pre>
sinfo
</pre>
This command offers a variety of options how to format the output. In order to get a detailed output while focusing on the nodes rather than the partitions, type
<pre>
sinfo -N -l
</pre>
An overview over the available partitions can be shown with
<pre>
scontrol show partition
</pre>
an the current queued and running jobs can be displayed using
<pre>
squeue
</pre>

== Executing a job in real-time ==
In order to allocate for instance 1 CPUs and 100MB of memory for real-time work, type
<pre>
salloc --mem-per-cpu=100 -n1 bash
</pre>
Your bash is now connected to the compute nodes. In order to execute a script use the srun-command
<pre>
srun my_script.sh
</pre>
Each srun-command you execute now is interpreted as a job step. The currently running job step of submitted jobs can be displayed using
<pre>
squeue -s
</pre>

You can also start a job by simply use the srun command and specify your requirements. In the following case, srun will allocate 100MB of memory and 1 CPU(s) for 1 task, only for the duration of execution.
<pre>
srun --mem-per-cpu=100 -n1 my_script.sh
</pre>
If resources are available your job will start immediately.

== Submitting a job for later execution ==

The most convenient way is to submit a job script for later execution. The top part of the script contains scheduling information for SLURM, the more information you provide here, the better.

First of all, a job name is specified, followed by a maximum time. If your job exceeds this time, it will be killed. However, do not overestimate too much because short jobs might start earlier. Acceptable time formats include "minutes", "minutes:seconds", "hours:minutes:seconds", "days-hours", "days-hours:minutes" and "days-hours:minutes:seconds". The output file is set to be test-job(jobID).out and the partition to run the job on is "remeis".
The sbatch-script itself will not initiate any job but only allocate the resources. The ''ntasks'' and ''mem-per-cpu'' options advise the SLURM controller that job steps run within the allocation will launch a maximum of number tasks and to provide for sufficient resources.

The ''srun'' commands in the job script launch the job steps. The example below thus consists of two job steps. Each of the ''srun'' commands may have own requirements concerning memory any may also spawn less tasks than given in the header of the script file. However, the values in the header may never be exceeded!
<pre>
#!/bin/bash
#SBATCH --job-name my_first_job
#SBATCH --time 05:00
#SBATCH --output test-job_%A_%a.out
#SBATCH --error test-job_%A_%a.err
#SBATCH --partition=remeis
#SBATCH --ntasks=4
#SBATCH --mem-per-cpu=100
srun -l my_script1.sh
srun -l my_script2.sh
</pre>
The ''-l'' parameter of ''srun'' will print the task number in front of a line of stdout/err. You can submit this script by saving it in a file, e.g. ''my_first_job.slurm'', and sumitting it using
<pre>
cepheus:~> sbatch my_first_job.slurm
Submitted batch job 144
</pre>

You can check the estimated starting time of your job using
<pre>
squeue --start
</pre>

== Submitting a job array ==

In order to submit a array of jobs with the same requirements you have to modify your script file.
The script above is going to spawn 4 jobs each consisting of one srun command. Note the presence of the new environment variable ''${SLURM_ARRAY_TASK_ID}'' which might be useful for your work. In this example we start an isis-script with different input values. You can also simply use different scripts.
<pre>
#!/bin/bash
#SBATCH --partition remeis
#SBATCH --job-name important_job
#SBATCH --ntasks=1
#SBATCH --time 00:05:00
#SBATCH --output /home/dauser/tmp/jobscript_beta.%A_%a.out
#SBATCH --error /home/dauser/tmp/jobscript_beta.%A_%a.err
#SBATCH --array 0-3

cd /home/user/script/

COMMAND[0]="./sim_script.sl 0.00"
COMMAND[1]="./sim_script.sl 0.10"
COMMAND[2]="./sim_script.sl 0.20"
COMMAND[3]="./sim_script.sl 0.30"

srun /usr/bin/nice -n +19 ${COMMAND[$SLURM_ARRAY_TASK_ID]}
</pre>
As above, this code might be saved in a file, for example ''job.slurm'' can be executed using
<pre>
sbatch job.slurm
</pre>

If you need a specific machine to run your job on, you can use
<pre>
#SBATCH --nodelist=leo,draco
</pre>
If you have a job with high I/O and/or traffic on the network you can limit the number of jobs running simultaneously (to 2 in this example) by
<pre>
#SBATCH --array 0-3%2
</pre>
SLURM will only allocate resources on the given nodes. However, if all nodes in 'nodelist' cannot fulfill the job requirements, SLURM will also allocate other machines.

If you would like to cancel jobs 1, 2 and 3 from job array 20 use
<pre>
scancel 20_[1-3]
</pre>
Note that you might have to escape the brackets when using the above command, e.g.,
<pre>
tcsh:~> scancel 20_\[1-3\]
</pre>
If you want to cancel the whole array, ''scancel'' works as usual
<pre>
scancel 20
</pre>
Note, there is also the option to modify requirements of single jobs later using ''scontrol update job=101_1 ...''.

If you have jobs which are dependent on the result of others or if you want a more detailed description concerning job arrays you can find it in the official SLURM manual: [[https://slurm.schedmd.com/job_array.html]]

== Submitting a job array where each command needs to change into a different directory ==

In order to allow each command of the job array to change into an individual directory (as opposed to all into the same directory as above), modify the script as follows:
<pre>
#!/bin/bash
#SBATCH --partition remeis
#SBATCH --job-name important_job
#SBATCH --ntasks=1
#SBATCH --time 00:05:00
#SBATCH --output /home/dauser/tmp/jobscript_beta.%A_%a.out
#SBATCH --error /home/dauser/tmp/jobscript_beta.%A_%a.err
#SBATCH --array 0-3

DIR[0]="/home/user/dir1"
DIR[1]="/home/user/dir2"
DIR[2]="/userdata/user/dir3"
DIR[3]="/userdata/user/dir4"

cd ${DIR[$SLURM_ARRAY_TASK_ID]}

COMMAND[0]="./sim_script.sl 0.00"
COMMAND[1]="./sim_script.sl 0.10"
COMMAND[2]="./sim_script.sl 0.20"
COMMAND[3]="./sim_script.sl 0.30"

srun /usr/bin/nice -n +19 ${COMMAND[$SLURM_ARRAY_TASK_ID]}
</pre>
This also works with paths relative to the directory where the slurm script was submitted.

== Submitting a job array with varying number of tasks ==

This is not really a job "array". But to execute multiple jobs with different number of tasks one can use multiple
srun calls chained with an '&'. This will submit the jobs at once but allow one to specify job parameters individually
for each job.

Example: Simultaneous fit of multiple datasets with different functions

<syntaxhighlight lang="bash" line='line'>
#!/bin/bash
#SBATCH --job-name my_simultaneous_fit_%n
#SBATCH --time 05:00
#SBATCH --output test-job_%A_%a.out
#SBATCH --error test-job_%A_%a.err
#SBATCH --partition=remeis
#SBATCH --mem-per-cpu=100
srun -l my_complicated_fit.sh 2 --ntasks=2 & # my_complicated_fit fits 2 line centers -> needs 2 tasks
srun -l my_complicated_fit.sh 4 --ntasks=4 # my_complicated_fit fits 4 line centers -> needs 4 tasks
</syntaxhighlight>

== Graphical jobs (srun.x11) ==
Not all applications run only on the commandline. Slurm does not support graphical applications natively but there is a wrapper script available which allocates the resources on the cluster and then provides a [[screen]] session inside a running [[SSH|SSH-session]] to the host where the resources have been allocated on. For example
<pre>
[12:06]weber@lynx:~$ srun.x11
</pre>
results in a new shell :
<pre>
[12:06]weber@messier15:~$
</pre>

which forwards the window if you start a graphical program for example
<pre>
[12:06]weber@messier15:~$ kate
</pre>
would open the text editor [[https://de.wikipedia.org/wiki/Kate_(KDE) kate]]. However, this only uses the standard resources set for the remeis partition. If you have other requirements you can also specify these in exactly the same way as for ''srun'':
<pre>
[12:06]weber@lynx:~$ srun.x11 --mem=2G
</pre>
would allocate 2GB of memory for the application.

== Using the ''erosita'' partition (serpens)==

If you are allowed to use the eRosita Partition, contact a SLURM admin (eg. [mailto:simon.kreuzer@fau.de simon.kreuzer@fau.de]). Once your username is added to the list of privileged users, you just have to add
<pre>
#SBATCH --partition=erosita
#SBATCH --account=erosita
</pre>
to your jobfiles.

== Other useful commands ==

* ''sstat'' Real-time status information of your running jobs

* ''sattach <jobid.stepid>'' Attach to stdI/O of one of your running jobs

* ''scancel [OPTIONS...] [job_id[_array_id][.step_id]] [job_id[_array_id][.step_id]...]'' Cancel the execution of one of your job arrays/jobs/job steps.

* ''scontrol'' Administration tool, you can for example use this to modify the requirements of your jobs. You can for exaple show your jobs ''show jobs'' or update the time limit ''update JobId= TimeLimit=2''.

* ''smap'' graphically view information about Slurm jobs, partitions, and set configurations parameters.

* ''sview'' graphical user interface for those who prefer clicking over typing. X-Server required.

= SLURM and MPI =
== About MPI ==
MPI (the Message Passing Interface) makes it possible to run parallel processes on CPUs of different hosts. To do so it uses TCP packets to communicate via the normal network connection. Some tasks can profit a lot of using more cores for computation.
At Remeis MPICH2 is used for initialisation of MPI tasks which is well supported within Slurm. The process manager is called '''pmi2''' and is set as default for srun. If an older MPI process manager is needed, for example for older MPI applications used in '''torque''', it can be set with
<pre>
#SBATCH --mpi=
</pre>
in the submission script.
<pre>
srun --mpi=list
</pre>
provides a list of supported MPI process managers.

The implementation of MPI for SLang/ISIS is called '''SLMPI'''.

== Best practice for MPI tasks ==

The usage of MPI might cause continuously high network traffic especially on the host which holds the master process. Please consider this when deciding which nodes are used for the job. It's a good idea to provide servers (e.g. leo or lupus) with the ''--nodelist='' option one of which is then used to hold the master process since nobody is sitting in front of it and trying to use a browser. Additional nodes are allocated automatically by Slurm if required to fit the ''--ntasks'' / ''-n'' option.

MPI jobs depend on all allocated nodes to be up and running properly, so I'd like to use this opportunity to remind about shutting down/rebooting PCs on your own without any permission can abort a whole MPI job.

== Requirements and Tips ==
To use MPI obviously the application or function used should support MPI. Examples range from programs written in C using some MPI features and compiled with the ''mpicc'' compiler to common ISIS-functions such as ''mpi_emcee'' or ''mpi_fit_pars''.

Keep in mind that everything in the compiled programs/scripts which is not an MPI compatible function is executed on each node on its own. For example in ISIS with ''-n 20'':
<pre>
fit_counts;
</pre>
would fit the defined function to the dataset 20 times at once. That's not very helpful so think about which tasks should be performed in the actual MPI process. Special care has to be taken if something has to be saved as a file. Consider:
<pre>
save_par("test.par");
</pre>
with ''-n 20''. This would save the current fit parameters to '''test.par''' in the working directory 20 times at exactly the same time. This might be helpful if the file is needed on the scratch disk of each node, but doing this on for example ''/userdata'' can cause serious trouble. The function ''mpi_master_only'' can be used to perform a user defined task in an MPI job only once. Best way is to only submit an MPI job to Slurm which only contains actual MPI functions. If some models in ISIS are used which output something to stdout or stderr while loading these messages are also generated 20 times since it's loaded in each process individually.

== Usage ==
If the job is a valid MPI process then the submission works exactly like for any other job:
<pre>
#!/bin/bash
#SBATCH --job-name my_first_mpi_job
#SBATCH ...
#SBATCH --ntasks=20
cd /my/working/dir
srun /usr/bin/nice -n +15 ./my_mpi_script
</pre>
It might be necessary to set a higher memory usage than for the according non MPI job since some applications try to limit the network traffic by just copying the required data to each node in the first place.

Also make sure that if it is necessary to specify the number of child processes in the application itself, set it to the same as with the ''--ntasks'' / ''-n'' option in the submission. An example would be the ''num_slaves'' qualifier in ''mpi_emcee''.

Note that the ''srun'' command does not contain ''mpiexec'' or ''mpirun'' which were used in older versions of MPI to launch the processes. The processes manager ''pmi2'' is built into Slurm and makes it possible that Slurm itself can initialize the network communication with the ''srun'' command only.

Of course it's also possible to run the MPI process directly from the commandline. As an example let's have a look at the calculation of pi with the MPI program ''cpi''. The program comes with the source code of MPICH2 and is compiled in the ''check'' rule. It's located in
<pre>
/data/system/software/mpich/mpich-3.2/examples
</pre>
To run the calculation in 10 parallel processes directly from the commandline use:
<pre>
[1:11]weber@lynx:/data/system/software/mpich/mpich-3.2/examples> srun -n 10 ./cpi
Process 0 of 10 is on aquarius
Process 1 of 10 is on ara
Process 6 of 10 is on asterion
Process 2 of 10 is on ara
Process 8 of 10 is on asterion
Process 7 of 10 is on asterion
Process 3 of 10 is on aranea
Process 5 of 10 is on aranea
Process 4 of 10 is on aranea
Process 9 of 10 is on cancer
pi is approximately 3.1415926544231256, Error is 0.0000000008333325
wall clock time = 0.010601
</pre>
As we can see Slurm launched 10 processes distributed to aquarius, ara, asterion, aranea and cancer. Keep in mind that running MPI interactively doesn't really make sense. The best way to go is to write a submission script like explained above and let Slurm handle the initialisation.

GIT -- The Fast Version Control System

2018-07-30T18:53:23Z

Wilms: /* Usefull git commands */

= What is a GIT Repository? (by Matthias Kühnel) =

''A repository is a container for project files and a program, in this case 'git', handles the different versions of the files and takes care about merging of different file versions. That means many persons can work on the same project (or more precisely on the same files) simultaneously without taking care about the modifications of the other editors. So in principle each editor 'clones' the repository to his or her local computer, does some modifications and at last 'pushes' these changes back into the repository.''

= Clone existing repositories and add changes =

=== Get repository clone ===

==== git clone ====

If you want to use or contribute to a repository, you will first have to get a
full copy of it (called a "clone"):

<pre>
git clone git@serpens.sternwarte.uni-erlangen.de:<group>/<repository>
</pre>

where <tt><group></tt> is the group the <tt><repository></tt> belongs to
<ref>other repositories are distributed in the file system and can be obtained
via <code>git clone ssh://<user>@crux.sternwarte.uni-erlangen.de:/path/to/repo
</code>(always use this over <code>file://...</code> !)</ref>.

=== Add changes to the repository ===

Before changing anything in the new clone it is good practice<ref>it might be
necessary if the repo is located under gitlab</ref> to work on a new branch.

==== git checkout ====

To create a new branch and change to it, use:

<pre>
git checkout -b <branch-name>
</pre>

Choose a representative branch name for the feature you want to add or change!

==== git add / git commit====

In this fresh and new branch you can freely change anything you like. Keep your
changes logically together and add/commit every time you start working on a new
feature.

<pre>
git add <filename1> <filename2> ...
</pre>

adds all named files to the staging area. <code>git status</code> might prove
useful as it will list all untracked changes.

When you have staged all necessary files, use

<pre>
git commit
</pre>

to apply your changes locally. (This will ask you for a commit message. See
[[GIT -- The Fast Version Control System#Good commit practice|here]] for examples on how to explain what you did).

==== git push ====

With

<pre>
git push origin <branch-name>
</pre>

your changes will be added to the global repository (in the new branch).
If the repository is located under gitlab and you want to provide your code
for everyone it is probably necessary to send a merge request. (See
[[GIT -- The Fast Version Control System#Merge request|here]] for more details)<ref>In smaller projects it might
be sufficient to directly push to the master branch</ref>.

==== git merge ====

To combine (merge) the branch ''feature'' with branch ''master'' of the
same repository it is sufficient to call

<pre>
git fetch origin
git checkout master
git merge feature
</pre>

and probably also

<pre>
git branch -d feature
</pre>

to delete the branch in your local repository and/or

<pre>
git push origin :feature
</pre>

to delete the ''feature'' branch on the remote repository

= Create your own repository =

The most easy way to create a new repository (empty or from existing code)
is to use the [http://www.sternwarte.uni-erlangen.de/gitlab gitlab] interface.
Here you will also find first steps you want to do before start working.

However, if you do not want to use gitlab you can call

<pre>
git init --bare --shared
</pre>

in an empty folder. This, obviously empty, repository can then get pulled with

<pre>
git sh://<user>@curx.sternwarte.uni-erlangen.de:/path/to/folder
</pre>

and following the steps to
[[GIT -- The Fast Version Control System#Clone existing repositories and add changes|clone a repository]] and add
files.

==== Gitignore ====

For many projects (especially latex) it is very convenient to prevent you and
others from adding temporary or unnecessary files. This can be done by creating
a file called <code>.gitignore</code> in the root of the directory.

Example contents of <code>.gitignore</code> for a latex project:

<pre>
#
# git ignore file for TeX files
#
*~
*.aux
*.log
*.bbl
*.blg
*.bak
</pre>

In this example no file ending in <code>~, .aux, .log, .bbl, .blg,</code> or
<code>.bak</code> can get pushed to the repository.
Be aware that <code>.gitignore</code> only prevents files from getting pushed.
It does not affect files that are already part of the repository. So every file
that is added before the <code>.gitignore</code> was added must be explicitly
removed with <code>git rm <filename1> <filename2> ...</code> (also <code>git
push origin master</code> to apply it to the remote repository).

= Configure git =

Every time you commit changes to a repository your message is appended with
your name and mail address. If you have not specified a name and/or a mail
address you can do this (globally) with

<pre>
git config --global user.name "John Doe"
git config --global user.email johndoe@example.com
</pre>

This will also overwrite existing entries, in case your mail address has
changed.

= Gitlab =

The gitlab interface provides a powerful overview of all projects you are
involved in. Also it gives you hints about what you should do with a fresh
repository.

To create a new repository you first have to log in at
[http://www.sternwarte.uni-erlangen.de/gitlab www.sternwarte.uni-erlangen.de/gitlab]

For creating the new repository just click on the "new project" button.
Following the steps you will end up with a fresh repository.

=== Good commit practice ===

When you contribute to a repository there are a few rules for best practice
which make life much more easier:

<ul>
<li>
every time you work on a new (or old) feature
do your changes in a new branch with a meaningful name.
</li>
<li>
commit frequently and each time for separate changes/features that are not related to
each other
</li>
<li>
commit messages should start with a <50 character summary in
''imperative mode''. This is a headline! Capitalize the first word and no periods.
A more complete description of what you did, where, and how, may follow
'''after''' a blank line.
Example commit message:
<pre>
Add awesome_feature

This adds the awesome feature to foo by using the functionality
bar. foo may now be unstable when used with out of range values.
</pre>

Although this message is very generic here, notice the ~80 character
line break for better appearance.

In general try to complete the following sentence with your summary:
"With this commit you <insert summary here>"

In the description explain why you did something, how did you accomplish it
and what are the consequences.
</li>
</ul>

Further information about good commit practice can be found on
[https://chris.beams.io/posts/git-commit/ this web page].

=== Merge request ===

When you work on a repository located on gitlab, it might be necessary to fill
a merge request. A merge request informs the maintainers of the repository that
a new feature is available and ready for publication.

The easiest way to send a merge request is to follow the link that is given in your
command line when you've pushed your branch.

On this page just select one maintainer to send the request to and check the mark for
"delete branch after merge". You are not forced to delete your branch, but it is very
good practice. Under normal conditions when you will work any further on the same feature
(e.g., bug fixing) just checkout a new branch instead of keeping old ones. This will just
lead to an unnecessary amount of dead branches.

= Useful git commands =

{|
| git log || list log overview
|-
| git log --stat || list commits with stats
|-
| git log --oneline || display only first line of commit messages
|-
| git branch || list local branches
|-
| git branch -v || list local branches with more information
|-
| git branch -d <branch-name> || delete branch <branch-name>
|-
| git branch <branch-name> || add branch <branch-name>
|-
| git remote || list repository urls
|-
| git remote rename <old> <new> || rename <old> url to <new> url
|-
| git remote add <url-name> <address> || add new remote address under <url-name>
|-
| git push <url-name> <branch-name> || push <branch-name> to <url-name>
|-
| git push <url-name> :<branch-name> || delete <branch-name> from remote <url-name>
|-
| git status || list untracked files/changes
|-
| git add <filename> || add <filename> to staging
|-
| git commit || commit staged changes
|}



More information about the different tools of git can be found in the man page
<code>git <tool> --help</code> or [https://git-scm.com/docs here].

= git and latexdiff =
Find the version you want to compare your current document with via
<pre> git log </pre>

produce a pdf showing the differences between the two files via

<pre>
latexdiff-vc --git --flatten -r long_weird_number_of_the_older_commit --pdf --disable-citation-markup file.tex
</pre>

No need to checkout the older version! See latexdiff documentation for further options.

= Notes =



[[Category:GIT]]