sinq-reflectometry/eos
0
1
Fork 0
Code Issues Pull Requests 1 Actions Packages Projects Releases 1 Wiki Activity

man pages corrected and reformated

Browse Source
This commit is contained in:
stahn
2024-02-29 08:44:45 +01:00
parent 64b88690cc
commit fb12d4aff4
2 changed files with 96 additions and 65 deletions
Download Patch File Download Diff File Expand all files Collapse all files

161
man.md
View File

@@ -1,9 +1,17 @@
---
author: Jochen Stahn
date: 2024-02-29
title: \textbf{EOS} \linebreak
python script to reduce reflectivity data \linebreak
for Amor @ SINQ, PSI
...
# documentation for **eos.py**
---
**eos** is a python program used at the neutron reflectometer *Amor* at *SINQ*
**eos** is a python program used at the neutron reflectometer *Amor* at *SINQ,
Paul Scherrer Institut, Switzerland*
to turn *raw data*
into reduced an *orso* comptible *reflectivity file*.
into reduced an [*orso*](https://www.reflectometry.org/advanced_and_expert_level/file_format) compatible *reflectivity file*.
raw: *nexus hdf5* format:
@@ -21,6 +29,8 @@ reduced: *orso reflectivity* format:
- array with basic or expanded reflectivity data (in the simplest version: the *reflectivity curve*)
---
## environment
**eos** (version 2.0 and later) was developen with python3.9.
@@ -29,9 +39,9 @@ The following (non-trivial) python modules are required:
- `numpy`
- `h5py`
- `orsopy`
- [`orsopy`](https://orsopy.readthedocs.io/en/latest)
## usage
# usage
**eos** can read one or several *.hdf* files for one or several instrument settings, and
it creates one or several reflectivity curves or intensity maps.
@@ -48,50 +58,50 @@ it creates one or several reflectivity curves or intensity maps.
- define reduction steps
- define the output path and name
### communicate file numbers and path information
## communicate file numbers and path information
```
input data:
-d DATAPATH, --dataPath DATAPATH
relative path to directory with .hdf files
-Y YEAR, --year YEAR year the measurement was performed
-n FILEIDENTIFIER [FILEIDENTIFIER ...], --fileIdentifier FILEIDENTIFIER [FILEIDENTIFIER ...]
file number(s) or offset (if negative)
-r NORMALISATIONFILEIDENTIFIER [NORMALISATIONFILEIDENTIFIER ...], --normalisationFileIdentifier NORMALISATIONFILEIDENTIFIER [NORMALISATIONFILEIDENTIFIER ...]
file number(s) of normalisation measurement
-d DATAPATH, --dataPath DATAPATH
relative path to directory with .hdf files
-Y YEAR, --year YEAR year the measurement was performed
-sub SUBTRACT, --subtract SUBTRACT
R(q_z) curve to be subtracted (in .Rqz.ort format
```
**minimum**
### minimum
purposes:
#### purposes:
- fast access to human-readable meta data in the output header
- get an idea about $q_z$ range and statistics
actions:
#### actions:
- read in one raw data file
- convert the event stream into an $I(\lambda, \alpha_f)$ map
- project this map onto $q_z$ to give an $I(q_z)$ curve
- write this curve in *orso* format to disk
> example:
>
> `> python eos.py -n 456 -o foo`
> looks for the file `amor<year>n000456.hdf` in one of the default locations
> (`./`, `./raw/`, `../raw`, local raw data directory on Amor) and
> writes the output to `foo.Rqz.ort`.
#### example:
**with normalisation**
`> python eos.py -n 456 -o foo`
looks for the file `amor<year>n000456.hdf` in one of the default locations
(`./`, `./raw/`, `../raw`, local raw data directory on Amor) and
writes the output to `foo.Rqz.ort`.
purposes:
### with normalisation
#### purposes:
- fast access to human-readable meta data in the output header
- get a reduced and (partially) corrected reflectivity curve
actions:
#### actions:
- read in raw data file(s) and raw normalisation file(s)
- convert the normalisation measurement into a $N(\lambda, z_\mathrm{detector})$
@@ -102,15 +112,15 @@ actions:
- project this map onto $q_z$ to give a $R(q_z)$ curve (not necessarily scaled)
- write this curve in *orso* format to disk
> example:
>
> `> python eos.py -n 456 -r 123 -o foo`
> looks for the files `amor<year>n000456.hdf` (reflectivity) and `amor<year>n000123.hdf`
> (normalisation) in one of the default locations
> (`./`, `./raw/`, `../raw`, local raw data directory on Amor) and
> writes the output to `foo.Rqz.ort`.
#### example:
**read multiple files**
`> python eos.py -n 456 -r 123 -o foo`
looks for the files `amor<year>n000456.hdf` (reflectivity) and `amor<year>n000123.hdf`
(normalisation) in one of the default locations
(`./`, `./raw/`, `../raw`, local raw data directory on Amor) and
writes the output to `foo.Rqz.ort`.
### read multiple files
- **for the same instrument parameter set**
@@ -119,13 +129,13 @@ actions:
Each number range is defined by a start value, an optional stop value and an
optional increment. Various ranges are separated by a ','.
> example:
>
> `20-25:2,28-30,40`
> resolves into the list
> `[20, 22, 24, 28, 29, 30, 40]`
#### example:
`20-25:2,28-30,40`
resolves into the list
`[20, 22, 24, 28, 29, 30, 40]`
action:
#### action:
Effectively, the event streams found in the the various files are merged and
processed together.
@@ -138,28 +148,33 @@ actions:
curves for more than one argument are separated in the output file
by the separator `# data-set: <identifier>`.
> example:
>
> `> python eos.py -n 20,21 30 -r 123 -o foo`
> results in two reflectivity curves, the first made from files #20 and #21,
> the second from file #30. Both are saved in `foo.Rqz.ort`.
#### example:
`> python eos.py -n 20,21 30 -r 123 -o foo`
results in two reflectivity curves, the first made from files #20 and #21,
the second from file #30. Both are saved in `foo.Rqz.ort`.
warning:
#### warning:
`-r` does accept only one argument!
**misc.**
### misc.
**year**: The raw file name is created using the file number and the actual year. In case
#### year
The raw file name is created using the file number and the actual year. In case
the data to be processed were recorded in a previous year, this must be
explicitely stated with
`-Y <year>`.
**path**: The default location for the output (and for starting the search for the input files)
#### path
The default location for the output (and for starting the search for the input files)
iis the present working directory. This can be altered by using the argument
`-d <path>`.
**subtract $q_z$-dependent curve**:
#### subtract $q_z$-dependent curve
It is possible to provide a $R(q_z)$ curve in `.Rqz.ort` format to be subtracted
from the reduced data. E.g. to emphasize the high-$q$ region on a linear scale, or
to illustrate changes in a series of measurements. The argument is
@@ -205,18 +220,18 @@ where `.orb` will be the future nexus comptibe output format.
### $q_z$ binning
The $R(\lambda, \alpha_f)$ arrays are projected onto a $q_z$ grid with bin boundaries
defined by:
The $R(\lambda, \alpha_f)$ arrays are projected onto a $q_z$ grid, which is linear between
$q_z = 0$ and $q_z = q_\mathrm{base} = 0.1\,\mbox{\AA}^{-1}$, and exponential for
$q_z > q_\mathrm{base}$. The bin boundaries are defined by:
$q_{z\,i} \in [0,\, c,\, 2c,\, 3c,\, \dots \hat\imath c] \qquad \forall \quad q_z \le q_\mathrm{base}$,\quad $\hat\imath = q_\mathrm{base} / c$
$q_{z\,i} \in [0,\, a,\, 2a,\, 3a,\, \dots \hat\imath a] \qquad \forall \quad q_z \le q_\mathrm{base}$,\quad $\hat\imath = q_\mathrm{base} / a$
$q_{z\,\hat\imath+j} \in [q_\mathrm{base} \cdot (1+c)^1, q_\mathrm{base} \cdot (1+c)^2, \dots q_\mathrm{base} \cdot (1+c)^j \dots \qquad \forall \quad q_z >q_\mathrm{base}$
$q_{z\,\hat\imath+j} \in [q_\mathrm{base} \cdot (1+a), q_\mathrm{base} \cdot (1+a)^2, \dots q_\mathrm{base} \cdot (1+a)^j \dots \qquad \forall \quad q_z >q_\mathrm{base}$
$q_\mathrm{base} = 0.1\,\mbox{\AA}^{-1}$ is fixed for the moment.
The *resolution* $c$ can be chosen with `-a` among the values
[0.005, 0.01, 0.02, 0.025, 0.04, 0.05, 0.1, 1]
The **output resolution** $a$ can be chosen with `-a` among the values
$a \in [0.005,\, 0.01,\, 0.02,\, 0.025,\, 0.04,\, 0.05,\, 0.1,\, 1]$
(this is restricted to ensure a *smooth* transition between the
linear and exponential regions).
linear and exponential regions). The best instrument resolution is $\sigma_{q_z} / q_z = 2.2\,\%$.
### intensity scaling
@@ -237,19 +252,19 @@ where `<interval>` is the time interval length in seconds. The chopping starts
`<stop>` seconds (default: end of the measurement).
All the resulting $R(q_z)$ curves are stored in one file, one after the other. An additional
column is added with the start time of the respective slize. This enables fast plotting.
column is added with the start time of the respective slize.
> example:
>
> `python -n 20-22 -r 123 -ts 60 1200 4000 -f foo`
> The event streams of the measurements #20, #21 and #22 are merged. All events before
> $t = 1200\,\mathrm{s}$ with respect to the start of meausrement #20 are discarded.
> Then until $t = 4020\,\mathrm{s}$ (or the end of measurement #22) a $R(q_z)$ curve is generated
> for each $60\,\mathrm{s}$ interval.
#### example:
`python -n 20-22 -r 123 -ts 60 1200 4000 -f foo`
The event streams of the measurements #20, #21 and #22 are merged. All events before
$t = 1200\,\mathrm{s}$ with respect to the start of meausrement #20 are discarded.
Then until $t = 4020\,\mathrm{s}$ (the starting time of the last slize is within the given
interval) a $R(q_z)$ curve is generated for each $60\,\mathrm{s}$ interval.
---
## masksing
## masking
```
masks:
@@ -265,6 +280,9 @@ masks:
q_z range
```
#### detector region
The specularely reflected intensity illuminated the detector only in a
limited region. To reduce noise, the **detector region of interest** is reduced by default
to the inner horizontal channels of the detector and the vertical channels
@@ -272,11 +290,24 @@ corresponding to the divergence of the beam.
These values can be overwirtten by using the keys `-y` and `-t` for absolute
finite angles or `-T` for the angular distance from the detector center.
#### $\lambda$
The **wavelength band** can be limited using `-l`, where the arguments are the
waveengths with unit `angstrom`.
wavelengths with unit `angstrom`.
#### $q_z$
The **$\mathbf{q_z}$ range** can de limited using `-q`, where the arguments are the momentum
transfer with unit `1/angstrom`.
transfers with unit `1/angstrom`.
#### default values
`-y 11 41 -l 2.0 15.0 -q 0.005 0.3`
For high-intensity specular neasurements, the angular region of interest is determined automatically.
In most cases this corresponds to `-T -0.7 0.7`.
The wavelength range should be adapted to the measurement mode (divergent, focused, polarised).
---
@@ -298,7 +329,7 @@ overwrite:
1-line orso sample model description
```
purposes:
#### purposes:
- debugging
- correctiion of wrong entries (due to communication problems)

BIN
man.pdf
View File

Binary file not shown.