rescalculator 2.0.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (41) hide show
  1. rescalculator-2.0.0/PKG-INFO +335 -0
  2. rescalculator-2.0.0/README.md +292 -0
  3. rescalculator-2.0.0/__init__.py +42 -0
  4. rescalculator-2.0.0/backends/__init__.py +71 -0
  5. rescalculator-2.0.0/backends/base.py +176 -0
  6. rescalculator-2.0.0/backends/numba_backend.py +332 -0
  7. rescalculator-2.0.0/backends/numpy_backend.py +148 -0
  8. rescalculator-2.0.0/backends/pytorch_backend.py +280 -0
  9. rescalculator-2.0.0/bifeo3prb.py +1 -0
  10. rescalculator-2.0.0/cartoons.py +212 -0
  11. rescalculator-2.0.0/convert_theta.py +833 -0
  12. rescalculator-2.0.0/convres.py +165 -0
  13. rescalculator-2.0.0/convres_sma.py +264 -0
  14. rescalculator-2.0.0/lattice.py +452 -0
  15. rescalculator-2.0.0/lattice_calculator_old.py +1443 -0
  16. rescalculator-2.0.0/lattice_calculator_procedural.py +1446 -0
  17. rescalculator-2.0.0/lattice_calculator_procedural2.py +1484 -0
  18. rescalculator-2.0.0/mycleanargs.py +45 -0
  19. rescalculator-2.0.0/mytile.py +11 -0
  20. rescalculator-2.0.0/numpyutils.py +1235 -0
  21. rescalculator-2.0.0/prefbifeo3.py +48 -0
  22. rescalculator-2.0.0/prefdemo.py +48 -0
  23. rescalculator-2.0.0/prefdemo_bifeo3.py +48 -0
  24. rescalculator-2.0.0/pyproject.toml +74 -0
  25. rescalculator-2.0.0/rescalc.py +1505 -0
  26. rescalculator-2.0.0/rescalc_batched.py +374 -0
  27. rescalculator-2.0.0/rescalc_torch.py +664 -0
  28. rescalculator-2.0.0/rescalculator.egg-info/PKG-INFO +335 -0
  29. rescalculator-2.0.0/rescalculator.egg-info/SOURCES.txt +67 -0
  30. rescalculator-2.0.0/rescalculator.egg-info/dependency_links.txt +1 -0
  31. rescalculator-2.0.0/rescalculator.egg-info/requires.txt +23 -0
  32. rescalculator-2.0.0/rescalculator.egg-info/top_level.txt +1 -0
  33. rescalculator-2.0.0/reslattice.py +1082 -0
  34. rescalculator-2.0.0/respython.py +911 -0
  35. rescalculator-2.0.0/setup.cfg +4 -0
  36. rescalculator-2.0.0/smabifeo3.py +39 -0
  37. rescalculator-2.0.0/smademo.py +42 -0
  38. rescalculator-2.0.0/sqwdemo.py +42 -0
  39. rescalculator-2.0.0/sqwdemo_bifeo3.py +42 -0
  40. rescalculator-2.0.0/testbifeo3.py +226 -0
  41. rescalculator-2.0.0/testconv.py +79 -0
@@ -0,0 +1,335 @@
1
+ Metadata-Version: 2.4
2
+ Name: rescalculator
3
+ Version: 2.0.0
4
+ Summary: Triple-Axis Spectrometer Resolution Calculator with Numba/PyTorch acceleration
5
+ Author-email: William Ratcliff <william.ratcliff@nist.gov>
6
+ Maintainer-email: William Ratcliff <william.ratcliff@nist.gov>
7
+ License: MIT
8
+ Project-URL: Homepage, https://github.com/scattering/rescalculator
9
+ Project-URL: Repository, https://github.com/scattering/rescalculator
10
+ Project-URL: Issues, https://github.com/scattering/rescalculator/issues
11
+ Keywords: neutron scattering,triple-axis spectrometer,resolution,TAS,Cooper-Nathans,pyspinw
12
+ Classifier: Development Status :: 4 - Beta
13
+ Classifier: Intended Audience :: Science/Research
14
+ Classifier: License :: OSI Approved :: MIT License
15
+ Classifier: Operating System :: OS Independent
16
+ Classifier: Programming Language :: Python :: 3
17
+ Classifier: Programming Language :: Python :: 3.9
18
+ Classifier: Programming Language :: Python :: 3.10
19
+ Classifier: Programming Language :: Python :: 3.11
20
+ Classifier: Programming Language :: Python :: 3.12
21
+ Classifier: Topic :: Scientific/Engineering :: Physics
22
+ Requires-Python: >=3.9
23
+ Description-Content-Type: text/markdown
24
+ Requires-Dist: numpy>=1.20
25
+ Requires-Dist: scipy>=1.7
26
+ Requires-Dist: lattice-calculator
27
+ Provides-Extra: fast
28
+ Requires-Dist: numba>=0.57; extra == "fast"
29
+ Provides-Extra: gpu
30
+ Requires-Dist: torch>=2.0; extra == "gpu"
31
+ Provides-Extra: all
32
+ Requires-Dist: numba>=0.57; extra == "all"
33
+ Requires-Dist: torch>=2.0; extra == "all"
34
+ Requires-Dist: pyspinw; extra == "all"
35
+ Requires-Dist: matplotlib; extra == "all"
36
+ Provides-Extra: dev
37
+ Requires-Dist: pytest; extra == "dev"
38
+ Requires-Dist: pytest-cov; extra == "dev"
39
+ Requires-Dist: black; extra == "dev"
40
+ Requires-Dist: isort; extra == "dev"
41
+ Requires-Dist: mypy; extra == "dev"
42
+ Requires-Dist: numba>=0.57; extra == "dev"
43
+
44
+ # Resolution Calculator for Triple-Axis Spectrometers
45
+
46
+ A Python library for computing resolution matrices and performing S(Q,w) convolutions for Triple-Axis Spectrometer (TAS) experiments. This package provides both NumPy (CPU) and PyTorch backends for flexible deployment.
47
+
48
+ Based on ResLib by Andrei Zheludev.
49
+
50
+ ## Features
51
+
52
+ - **Cooper-Nathans resolution formalism** with optional Popovici method
53
+ - **Dual backend support**: NumPy for CPU, PyTorch for GPU acceleration
54
+ - **Automatic device detection**: CUDA, MPS (Apple Silicon), or CPU
55
+ - **S(Q,w) convolution**: Integrate scattering cross-sections with resolution function
56
+ - **Batched operations**: Efficient computation for thousands of Q-points simultaneously
57
+
58
+ ## Installation
59
+
60
+ ### Requirements
61
+
62
+ - Python >= 3.9
63
+ - NumPy
64
+ - SciPy
65
+ - PyTorch (optional, for GPU acceleration)
66
+ - lattice-calculator
67
+
68
+ ### Install from PyPI
69
+
70
+ ```bash
71
+ pip install rescalculator
72
+ ```
73
+
74
+ ### Install from source
75
+
76
+ ```bash
77
+ git clone https://github.com/scattering/rescalculator.git
78
+ cd rescalculator
79
+ pip install -e .
80
+ ```
81
+
82
+ ### Setting up a conda environment
83
+
84
+ ```bash
85
+ conda create -n resolution python=3.11 pytorch numpy scipy matplotlib -c pytorch
86
+ conda activate resolution
87
+ pip install lattice-calculator
88
+ pip install -e .
89
+ ```
90
+
91
+ ## Quick Start
92
+
93
+ ### Basic Resolution Calculation
94
+
95
+ ```python
96
+ import numpy as np
97
+ from rescalculator import TASResolution
98
+ from lattice_calculator import Lattice, modvec
99
+
100
+ # Define crystal lattice
101
+ lattice = Lattice(
102
+ a=5.0, b=5.0, c=5.0,
103
+ alpha=90, beta=90, gamma=90,
104
+ orient1=np.array([[1, 0, 0]]),
105
+ orient2=np.array([[0, 1, 0]])
106
+ )
107
+
108
+ # Define experiment configuration
109
+ EXP = {
110
+ 'efixed': 14.7, # Fixed energy (meV)
111
+ 'infin': -1, # -1 for fixed Ef, +1 for fixed Ei
112
+ 'dir1': 1, # Monochromator scattering direction
113
+ 'dir2': 1, # Analyzer scattering direction
114
+ 'hcol': np.array([40, 40, 40, 40]), # Horizontal collimations (arcmin)
115
+ 'vcol': np.array([120, 120, 120, 120]), # Vertical collimations (arcmin)
116
+ 'mono': {'tau': 'pg(002)', 'mosaic': 30}, # Monochromator
117
+ 'ana': {'tau': 'pg(002)', 'mosaic': 30}, # Analyzer
118
+ 'sample': {'mosaic': 30}, # Sample mosaic
119
+ 'arms': [200, 200, 150, 150, 100], # Spectrometer arms (cm)
120
+ 'horifoc': -1, # Horizontal focusing (-1 = no focusing)
121
+ 'moncor': 1, # Monitor correction
122
+ }
123
+
124
+ # Create resolution calculator
125
+ res = TASResolution(lattice, backend='numpy')
126
+
127
+ # Define scan points
128
+ H = np.array([1.0, 1.05, 1.1])
129
+ K = np.zeros(3)
130
+ L = np.zeros(3)
131
+ W = np.array([5.0, 5.0, 5.0]) # Energy transfer (meV)
132
+ lattice.npts = len(H)
133
+
134
+ # Calculate resolution matrices
135
+ R0, RMS = res.ResMatS(H, K, L, W, [EXP] * len(H))
136
+
137
+ # R0: Prefactors (normalization)
138
+ # RMS: Resolution matrices in sample coordinates, shape (4, 4, npts)
139
+ print(f"Resolution matrix at first point:\n{RMS[:,:,0]}")
140
+ ```
141
+
142
+ ### S(Q,w) Convolution with Spin Waves
143
+
144
+ ```python
145
+ import numpy as np
146
+ from rescalculator import TASResolution, ConvolutionCalculator
147
+ from lattice_calculator import Lattice
148
+ from pyspinw import SpinW
149
+
150
+ # Set up spin wave model using pyspinw
151
+ model = SpinW()
152
+ model.genlattice(lat_const=[3.0, 3.0, 3.0], angled=[90, 90, 90])
153
+ model.addatom(r=[0, 0, 0], S=1, label='Fe')
154
+ model.gencoupling(max_distance=4.0)
155
+ model.addmatrix(label='J', value=1.0)
156
+ model.addcoupling(bond=0, mat_labels='J')
157
+ model.genmagstr(mode='direct', S=[[0], [0], [1]])
158
+
159
+ # Create S(Q,w) function
160
+ def sqw_function(h, k, l, w):
161
+ """Spin wave S(Q,w) at given (h,k,l,w)."""
162
+ spec = model.spinwave([[h], [k], [l]], use_surface_integrals=True)
163
+ # ... process spectrum ...
164
+ return intensity
165
+
166
+ # Set up convolution
167
+ lattice = Lattice(a=3.0, b=3.0, c=3.0, alpha=90, beta=90, gamma=90,
168
+ orient1=np.array([[1,0,0]]), orient2=np.array([[0,1,0]]))
169
+
170
+ conv = ConvolutionCalculator(
171
+ resolution=TASResolution(lattice, backend='numpy'),
172
+ sqw_function=sqw_function,
173
+ lattice=lattice
174
+ )
175
+
176
+ # Calculate convoluted intensity
177
+ H_scan = np.linspace(0.1, 0.9, 50)
178
+ K_scan = np.zeros(50)
179
+ L_scan = np.zeros(50)
180
+ W_scan = np.full(50, 5.0)
181
+
182
+ intensity = conv.convolve(H_scan, K_scan, L_scan, W_scan, EXP_list)
183
+ ```
184
+
185
+ ## Performance Notes
186
+
187
+ ### Backend Comparison
188
+
189
+ This library supports multiple backends with dramatically different performance:
190
+
191
+ | Backend | 1,000 pts | 10,000 pts | 100,000 pts | Speedup |
192
+ |---------|-----------|------------|-------------|---------|
193
+ | **Numba (CPU)** | 4 ms | 39 ms | 395 ms | **26x** |
194
+ | NumPy (CPU) | 105 ms | 998 ms | 10,288 ms | 1x |
195
+ | PyTorch (MPS) | 1,580 ms | 13,552 ms | OOM | 0.08x |
196
+
197
+ **Key findings:**
198
+
199
+ 1. **Numba is fastest** - JIT compilation with parallel execution gives ~26x speedup
200
+ 2. **Small matrices don't benefit from GPU**: Resolution calculations involve thousands of small (4x4 to 8x8) matrix operations, which don't parallelize efficiently on GPU
201
+ 3. **GPU overhead dominates**: Data transfer and kernel launch overhead exceeds computation time for small matrices
202
+ 4. **More points don't help GPU**: GPU performance actually degrades with more points due to memory pressure
203
+
204
+ **Recommendation:** Install with `pip install rescalculator[fast]` to get Numba acceleration. The default `backend='auto'` will automatically use Numba if available.
205
+
206
+ ### When to use each backend
207
+
208
+ - **Numba** (recommended): Best performance for all use cases
209
+ - **NumPy**: Fallback when Numba not available, always works
210
+ - **PyTorch**: Only for gradient computation or integration with PyTorch models
211
+
212
+ ### Memory Efficiency
213
+
214
+ The library handles large numbers of points efficiently:
215
+ - Numba/NumPy: Tested with 100,000+ points
216
+ - Memory scales linearly with point count
217
+ - Each point requires approximately 1-2 KB of memory
218
+
219
+ ## API Reference
220
+
221
+ ### TASResolution
222
+
223
+ ```python
224
+ class TASResolution(lattice, backend='auto')
225
+ ```
226
+
227
+ Main resolution calculator class.
228
+
229
+ **Parameters:**
230
+ - `lattice`: Lattice instance from lattice-calculator
231
+ - `backend`: 'auto', 'numba', 'numpy', or 'pytorch'
232
+
233
+ **Methods:**
234
+ - `ResMatS(H, K, L, W, EXP)`: Compute resolution matrices in sample coordinates
235
+ - `ResMat_vectorized(Q, W, EXP)`: Compute resolution matrices for Q magnitude array
236
+ - `set_backend(backend_type)`: Change computational backend
237
+
238
+ ### BatchedTASResolution
239
+
240
+ ```python
241
+ class BatchedTASResolution(lattice, device='auto')
242
+ ```
243
+
244
+ Fully batched resolution calculator using PyTorch tensor operations.
245
+
246
+ **Parameters:**
247
+ - `lattice`: Lattice instance
248
+ - `device`: 'auto', 'cuda', 'mps', or 'cpu'
249
+
250
+ **Methods:**
251
+ - `ResMat_batched(Q, W, EXP)`: Batched resolution calculation returning tensors
252
+ - `ResMatS(H, K, L, W, EXP)`: Resolution matrices in sample coordinates
253
+
254
+ ### ConvolutionCalculator
255
+
256
+ ```python
257
+ class ConvolutionCalculator(resolution, sqw_function, lattice)
258
+ ```
259
+
260
+ Convolves S(Q,w) with resolution function.
261
+
262
+ **Parameters:**
263
+ - `resolution`: TASResolution instance
264
+ - `sqw_function`: Function `f(h, k, l, w) -> intensity`
265
+ - `lattice`: Lattice instance
266
+
267
+ ### Experiment Configuration (EXP)
268
+
269
+ The EXP dictionary contains all spectrometer parameters:
270
+
271
+ ```python
272
+ EXP = {
273
+ 'efixed': 14.7, # Fixed energy (meV)
274
+ 'infin': -1, # -1 = fixed Ef, +1 = fixed Ei
275
+ 'dir1': 1, # Monochromator scattering direction (+1 or -1)
276
+ 'dir2': 1, # Analyzer scattering direction (+1 or -1)
277
+ 'hcol': [40, 40, 40, 40], # Horizontal collimations (arcmin)
278
+ 'vcol': [120, 120, 120, 120], # Vertical collimations (arcmin)
279
+ 'mono': {
280
+ 'tau': 'pg(002)', # Monochromator crystal
281
+ 'mosaic': 30, # Mosaic spread (arcmin)
282
+ 'rh': 1e6, # Horizontal radius (cm), 1e6 = flat
283
+ 'rv': 1e6, # Vertical radius (cm)
284
+ },
285
+ 'ana': {
286
+ 'tau': 'pg(002)', # Analyzer crystal
287
+ 'mosaic': 30,
288
+ 'rh': 1e6,
289
+ 'rv': 1e6,
290
+ },
291
+ 'sample': {
292
+ 'mosaic': 30, # Sample mosaic (arcmin)
293
+ 'vmosaic': 30, # Vertical sample mosaic (arcmin)
294
+ },
295
+ 'arms': [200, 200, 150, 150, 100], # L0, L1p, L1, L2, L3 (cm)
296
+ 'horifoc': -1, # Horizontal focusing (-1 = off)
297
+ 'moncor': 1, # Monitor correction (0 or 1)
298
+ 'method': 0, # 0 = Cooper-Nathans, 1 = Popovici
299
+ }
300
+ ```
301
+
302
+ Available monochromator/analyzer crystals:
303
+ - `'pg(002)'`: PG(002), tau = 1.873 A^-1
304
+ - `'pg(004)'`: PG(004), tau = 3.746 A^-1
305
+ - `'ge(111)'`: Ge(111), tau = 1.924 A^-1
306
+ - `'ge(220)'`: Ge(220), tau = 3.141 A^-1
307
+ - `'ge(311)'`: Ge(311), tau = 3.684 A^-1
308
+ - `'be(002)'`: Be(002), tau = 3.507 A^-1
309
+
310
+ ## Examples
311
+
312
+ See the `examples/` directory for complete working examples:
313
+
314
+ - `spinwave_convolution.py`: Ferromagnetic chain convolution with pyspinw
315
+ - `benchmark.py`: Performance comparison between backends
316
+
317
+ ## Dependencies
318
+
319
+ - [lattice-calculator](https://github.com/scattering/lattice-calculator): Crystal lattice calculations
320
+ - [pyspinw](https://github.com/scattering/pyspinw): Spin wave calculations (optional, for S(Q,w))
321
+
322
+ ## References
323
+
324
+ 1. Cooper, M. J. & Nathans, R. (1967). Acta Cryst. 23, 357-367.
325
+ 2. Popovici, M. (1975). Acta Cryst. A31, 507-513.
326
+ 3. Chesser, N. J. & Axe, J. D. (1973). Acta Cryst. A29, 160-169.
327
+ 4. Zheludev, A. ResLib (MATLAB version)
328
+
329
+ ## License
330
+
331
+ MIT License
332
+
333
+ ## Authors
334
+
335
+ William Ratcliff (NIST Center for Neutron Research)
@@ -0,0 +1,292 @@
1
+ # Resolution Calculator for Triple-Axis Spectrometers
2
+
3
+ A Python library for computing resolution matrices and performing S(Q,w) convolutions for Triple-Axis Spectrometer (TAS) experiments. This package provides both NumPy (CPU) and PyTorch backends for flexible deployment.
4
+
5
+ Based on ResLib by Andrei Zheludev.
6
+
7
+ ## Features
8
+
9
+ - **Cooper-Nathans resolution formalism** with optional Popovici method
10
+ - **Dual backend support**: NumPy for CPU, PyTorch for GPU acceleration
11
+ - **Automatic device detection**: CUDA, MPS (Apple Silicon), or CPU
12
+ - **S(Q,w) convolution**: Integrate scattering cross-sections with resolution function
13
+ - **Batched operations**: Efficient computation for thousands of Q-points simultaneously
14
+
15
+ ## Installation
16
+
17
+ ### Requirements
18
+
19
+ - Python >= 3.9
20
+ - NumPy
21
+ - SciPy
22
+ - PyTorch (optional, for GPU acceleration)
23
+ - lattice-calculator
24
+
25
+ ### Install from PyPI
26
+
27
+ ```bash
28
+ pip install rescalculator
29
+ ```
30
+
31
+ ### Install from source
32
+
33
+ ```bash
34
+ git clone https://github.com/scattering/rescalculator.git
35
+ cd rescalculator
36
+ pip install -e .
37
+ ```
38
+
39
+ ### Setting up a conda environment
40
+
41
+ ```bash
42
+ conda create -n resolution python=3.11 pytorch numpy scipy matplotlib -c pytorch
43
+ conda activate resolution
44
+ pip install lattice-calculator
45
+ pip install -e .
46
+ ```
47
+
48
+ ## Quick Start
49
+
50
+ ### Basic Resolution Calculation
51
+
52
+ ```python
53
+ import numpy as np
54
+ from rescalculator import TASResolution
55
+ from lattice_calculator import Lattice, modvec
56
+
57
+ # Define crystal lattice
58
+ lattice = Lattice(
59
+ a=5.0, b=5.0, c=5.0,
60
+ alpha=90, beta=90, gamma=90,
61
+ orient1=np.array([[1, 0, 0]]),
62
+ orient2=np.array([[0, 1, 0]])
63
+ )
64
+
65
+ # Define experiment configuration
66
+ EXP = {
67
+ 'efixed': 14.7, # Fixed energy (meV)
68
+ 'infin': -1, # -1 for fixed Ef, +1 for fixed Ei
69
+ 'dir1': 1, # Monochromator scattering direction
70
+ 'dir2': 1, # Analyzer scattering direction
71
+ 'hcol': np.array([40, 40, 40, 40]), # Horizontal collimations (arcmin)
72
+ 'vcol': np.array([120, 120, 120, 120]), # Vertical collimations (arcmin)
73
+ 'mono': {'tau': 'pg(002)', 'mosaic': 30}, # Monochromator
74
+ 'ana': {'tau': 'pg(002)', 'mosaic': 30}, # Analyzer
75
+ 'sample': {'mosaic': 30}, # Sample mosaic
76
+ 'arms': [200, 200, 150, 150, 100], # Spectrometer arms (cm)
77
+ 'horifoc': -1, # Horizontal focusing (-1 = no focusing)
78
+ 'moncor': 1, # Monitor correction
79
+ }
80
+
81
+ # Create resolution calculator
82
+ res = TASResolution(lattice, backend='numpy')
83
+
84
+ # Define scan points
85
+ H = np.array([1.0, 1.05, 1.1])
86
+ K = np.zeros(3)
87
+ L = np.zeros(3)
88
+ W = np.array([5.0, 5.0, 5.0]) # Energy transfer (meV)
89
+ lattice.npts = len(H)
90
+
91
+ # Calculate resolution matrices
92
+ R0, RMS = res.ResMatS(H, K, L, W, [EXP] * len(H))
93
+
94
+ # R0: Prefactors (normalization)
95
+ # RMS: Resolution matrices in sample coordinates, shape (4, 4, npts)
96
+ print(f"Resolution matrix at first point:\n{RMS[:,:,0]}")
97
+ ```
98
+
99
+ ### S(Q,w) Convolution with Spin Waves
100
+
101
+ ```python
102
+ import numpy as np
103
+ from rescalculator import TASResolution, ConvolutionCalculator
104
+ from lattice_calculator import Lattice
105
+ from pyspinw import SpinW
106
+
107
+ # Set up spin wave model using pyspinw
108
+ model = SpinW()
109
+ model.genlattice(lat_const=[3.0, 3.0, 3.0], angled=[90, 90, 90])
110
+ model.addatom(r=[0, 0, 0], S=1, label='Fe')
111
+ model.gencoupling(max_distance=4.0)
112
+ model.addmatrix(label='J', value=1.0)
113
+ model.addcoupling(bond=0, mat_labels='J')
114
+ model.genmagstr(mode='direct', S=[[0], [0], [1]])
115
+
116
+ # Create S(Q,w) function
117
+ def sqw_function(h, k, l, w):
118
+ """Spin wave S(Q,w) at given (h,k,l,w)."""
119
+ spec = model.spinwave([[h], [k], [l]], use_surface_integrals=True)
120
+ # ... process spectrum ...
121
+ return intensity
122
+
123
+ # Set up convolution
124
+ lattice = Lattice(a=3.0, b=3.0, c=3.0, alpha=90, beta=90, gamma=90,
125
+ orient1=np.array([[1,0,0]]), orient2=np.array([[0,1,0]]))
126
+
127
+ conv = ConvolutionCalculator(
128
+ resolution=TASResolution(lattice, backend='numpy'),
129
+ sqw_function=sqw_function,
130
+ lattice=lattice
131
+ )
132
+
133
+ # Calculate convoluted intensity
134
+ H_scan = np.linspace(0.1, 0.9, 50)
135
+ K_scan = np.zeros(50)
136
+ L_scan = np.zeros(50)
137
+ W_scan = np.full(50, 5.0)
138
+
139
+ intensity = conv.convolve(H_scan, K_scan, L_scan, W_scan, EXP_list)
140
+ ```
141
+
142
+ ## Performance Notes
143
+
144
+ ### Backend Comparison
145
+
146
+ This library supports multiple backends with dramatically different performance:
147
+
148
+ | Backend | 1,000 pts | 10,000 pts | 100,000 pts | Speedup |
149
+ |---------|-----------|------------|-------------|---------|
150
+ | **Numba (CPU)** | 4 ms | 39 ms | 395 ms | **26x** |
151
+ | NumPy (CPU) | 105 ms | 998 ms | 10,288 ms | 1x |
152
+ | PyTorch (MPS) | 1,580 ms | 13,552 ms | OOM | 0.08x |
153
+
154
+ **Key findings:**
155
+
156
+ 1. **Numba is fastest** - JIT compilation with parallel execution gives ~26x speedup
157
+ 2. **Small matrices don't benefit from GPU**: Resolution calculations involve thousands of small (4x4 to 8x8) matrix operations, which don't parallelize efficiently on GPU
158
+ 3. **GPU overhead dominates**: Data transfer and kernel launch overhead exceeds computation time for small matrices
159
+ 4. **More points don't help GPU**: GPU performance actually degrades with more points due to memory pressure
160
+
161
+ **Recommendation:** Install with `pip install rescalculator[fast]` to get Numba acceleration. The default `backend='auto'` will automatically use Numba if available.
162
+
163
+ ### When to use each backend
164
+
165
+ - **Numba** (recommended): Best performance for all use cases
166
+ - **NumPy**: Fallback when Numba not available, always works
167
+ - **PyTorch**: Only for gradient computation or integration with PyTorch models
168
+
169
+ ### Memory Efficiency
170
+
171
+ The library handles large numbers of points efficiently:
172
+ - Numba/NumPy: Tested with 100,000+ points
173
+ - Memory scales linearly with point count
174
+ - Each point requires approximately 1-2 KB of memory
175
+
176
+ ## API Reference
177
+
178
+ ### TASResolution
179
+
180
+ ```python
181
+ class TASResolution(lattice, backend='auto')
182
+ ```
183
+
184
+ Main resolution calculator class.
185
+
186
+ **Parameters:**
187
+ - `lattice`: Lattice instance from lattice-calculator
188
+ - `backend`: 'auto', 'numba', 'numpy', or 'pytorch'
189
+
190
+ **Methods:**
191
+ - `ResMatS(H, K, L, W, EXP)`: Compute resolution matrices in sample coordinates
192
+ - `ResMat_vectorized(Q, W, EXP)`: Compute resolution matrices for Q magnitude array
193
+ - `set_backend(backend_type)`: Change computational backend
194
+
195
+ ### BatchedTASResolution
196
+
197
+ ```python
198
+ class BatchedTASResolution(lattice, device='auto')
199
+ ```
200
+
201
+ Fully batched resolution calculator using PyTorch tensor operations.
202
+
203
+ **Parameters:**
204
+ - `lattice`: Lattice instance
205
+ - `device`: 'auto', 'cuda', 'mps', or 'cpu'
206
+
207
+ **Methods:**
208
+ - `ResMat_batched(Q, W, EXP)`: Batched resolution calculation returning tensors
209
+ - `ResMatS(H, K, L, W, EXP)`: Resolution matrices in sample coordinates
210
+
211
+ ### ConvolutionCalculator
212
+
213
+ ```python
214
+ class ConvolutionCalculator(resolution, sqw_function, lattice)
215
+ ```
216
+
217
+ Convolves S(Q,w) with resolution function.
218
+
219
+ **Parameters:**
220
+ - `resolution`: TASResolution instance
221
+ - `sqw_function`: Function `f(h, k, l, w) -> intensity`
222
+ - `lattice`: Lattice instance
223
+
224
+ ### Experiment Configuration (EXP)
225
+
226
+ The EXP dictionary contains all spectrometer parameters:
227
+
228
+ ```python
229
+ EXP = {
230
+ 'efixed': 14.7, # Fixed energy (meV)
231
+ 'infin': -1, # -1 = fixed Ef, +1 = fixed Ei
232
+ 'dir1': 1, # Monochromator scattering direction (+1 or -1)
233
+ 'dir2': 1, # Analyzer scattering direction (+1 or -1)
234
+ 'hcol': [40, 40, 40, 40], # Horizontal collimations (arcmin)
235
+ 'vcol': [120, 120, 120, 120], # Vertical collimations (arcmin)
236
+ 'mono': {
237
+ 'tau': 'pg(002)', # Monochromator crystal
238
+ 'mosaic': 30, # Mosaic spread (arcmin)
239
+ 'rh': 1e6, # Horizontal radius (cm), 1e6 = flat
240
+ 'rv': 1e6, # Vertical radius (cm)
241
+ },
242
+ 'ana': {
243
+ 'tau': 'pg(002)', # Analyzer crystal
244
+ 'mosaic': 30,
245
+ 'rh': 1e6,
246
+ 'rv': 1e6,
247
+ },
248
+ 'sample': {
249
+ 'mosaic': 30, # Sample mosaic (arcmin)
250
+ 'vmosaic': 30, # Vertical sample mosaic (arcmin)
251
+ },
252
+ 'arms': [200, 200, 150, 150, 100], # L0, L1p, L1, L2, L3 (cm)
253
+ 'horifoc': -1, # Horizontal focusing (-1 = off)
254
+ 'moncor': 1, # Monitor correction (0 or 1)
255
+ 'method': 0, # 0 = Cooper-Nathans, 1 = Popovici
256
+ }
257
+ ```
258
+
259
+ Available monochromator/analyzer crystals:
260
+ - `'pg(002)'`: PG(002), tau = 1.873 A^-1
261
+ - `'pg(004)'`: PG(004), tau = 3.746 A^-1
262
+ - `'ge(111)'`: Ge(111), tau = 1.924 A^-1
263
+ - `'ge(220)'`: Ge(220), tau = 3.141 A^-1
264
+ - `'ge(311)'`: Ge(311), tau = 3.684 A^-1
265
+ - `'be(002)'`: Be(002), tau = 3.507 A^-1
266
+
267
+ ## Examples
268
+
269
+ See the `examples/` directory for complete working examples:
270
+
271
+ - `spinwave_convolution.py`: Ferromagnetic chain convolution with pyspinw
272
+ - `benchmark.py`: Performance comparison between backends
273
+
274
+ ## Dependencies
275
+
276
+ - [lattice-calculator](https://github.com/scattering/lattice-calculator): Crystal lattice calculations
277
+ - [pyspinw](https://github.com/scattering/pyspinw): Spin wave calculations (optional, for S(Q,w))
278
+
279
+ ## References
280
+
281
+ 1. Cooper, M. J. & Nathans, R. (1967). Acta Cryst. 23, 357-367.
282
+ 2. Popovici, M. (1975). Acta Cryst. A31, 507-513.
283
+ 3. Chesser, N. J. & Axe, J. D. (1973). Acta Cryst. A29, 160-169.
284
+ 4. Zheludev, A. ResLib (MATLAB version)
285
+
286
+ ## License
287
+
288
+ MIT License
289
+
290
+ ## Authors
291
+
292
+ William Ratcliff (NIST Center for Neutron Research)
@@ -0,0 +1,42 @@
1
+ """
2
+ Resolution Calculator for Triple Axis Spectrometer
3
+
4
+ This package provides GPU-accelerated resolution calculations using PyTorch.
5
+ It supports both NumPy (CPU) and PyTorch (GPU) backends for flexible deployment.
6
+
7
+ Key components:
8
+ - TASResolution: Resolution matrix calculator with GPU support
9
+ - ConvolutionCalculator: S(Q,w) convolution with resolution function
10
+ - Backends: NumPy and PyTorch computational backends
11
+
12
+ Example usage:
13
+ from rescalculator_pytorch import TASResolution, get_backend
14
+ from lattice_calculator import Lattice, Orientation
15
+
16
+ # Initialize backend (auto-detects GPU)
17
+ backend = get_backend('auto')
18
+
19
+ # Set up lattice
20
+ lattice = Lattice(a=5.0, b=5.0, c=5.0, ...)
21
+
22
+ # Create resolution calculator
23
+ res = TASResolution(lattice, backend='pytorch')
24
+
25
+ # Calculate resolution matrices
26
+ R0, RMS = res.ResMatS(H, K, L, W, EXP)
27
+ """
28
+
29
+ __author__ = 'William Ratcliff'
30
+ __version__ = '2.0.0'
31
+
32
+ from .backends import get_backend, current_backend
33
+ from .rescalc_torch import TASResolution, ConvolutionCalculator
34
+ from .rescalc_batched import BatchedTASResolution
35
+
36
+ __all__ = [
37
+ 'TASResolution',
38
+ 'BatchedTASResolution',
39
+ 'ConvolutionCalculator',
40
+ 'get_backend',
41
+ 'current_backend',
42
+ ]