diff --git a/man.md b/man.md index ee93ab3..a146727 100644 --- a/man.md +++ b/man.md @@ -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 `amorn000456.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 `amorn000456.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 `amorn000456.hdf` (reflectivity) and `amorn000123.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 `amorn000456.hdf` (reflectivity) and `amorn000123.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: `. - > 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 `. -**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 `. -**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 `` is the time interval length in seconds. The chopping starts `` 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) diff --git a/man.pdf b/man.pdf index 1c969d2..e850228 100644 Binary files a/man.pdf and b/man.pdf differ