Metadata-Version: 2.3
Name: thztools
Version: 0.5.4
Summary: Data analysis software tools for terahertz time-domain spectroscopy (THz-TDS)
Project-URL: Documentation, https://dodge-research-group.github.io/thztools/
Project-URL: Issues, https://github.com/dodge-research-group/thztools/issues
Project-URL: Discussion, https://github.com/dodge-research-group/thztools/discussions
Project-URL: Source, https://github.com/dodge-research-group/thztools
Author-email: Jonathan Posada Loaiza <jonathan.posada1@udea.edu.co>, Santiago Higuera-Quintero <santiago.higuera@itp3.uni-stuttgart.de>, Alireza Noori <alireza_noori@sfu.ca>, Laleh Mohtashemi <lalehmo@gmail.com>, "R. P. Hall" <rph4@sfu.ca>, Naod Ayalew Yimam <nayimam@gmail.com>, "J. Steven Dodge" <jsdodge@sfu.ca>
Maintainer-email: Steve Dodge <jsdodge@sfu.ca>
License-Expression: MIT
License-File: LICENSE
Keywords: THz,data analysis,terahertz,time-domain spectroscopy
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: Implementation :: CPython
Classifier: Programming Language :: Python :: Implementation :: PyPy
Classifier: Topic :: Scientific/Engineering
Requires-Python: >=3.8
Requires-Dist: numpy
Requires-Dist: scipy
Description-Content-Type: text/markdown

<div style="text-align: center">
<picture>
  <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/dodge-research-group/thztools/main/docs/source/_static/thztools_logo_dark.svg" width="600">
  <source media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/dodge-research-group/thztools/main/docs/source/_static/thztools_logo.svg" width="600">
  <img alt="THzTools logo." src="https://raw.githubusercontent.com/dodge-research-group/thztools/main/docs/source/_static/thztools_logo.svg" width="600">
</picture>
</div>

THzTools is an open-source Python package for data analysis in terahertz time-domain spectroscopy
(THz-TDS). As the name suggests, THz-TDS involves measurements of terahertz-frequency
electromagnetic waveforms that are acquired as a function of *time*, which users typically
represent as a function of *frequency* for analysis. THzTools makes it easier for researchers
to use statistically optimal methods for doing this analysis, as described in [L. Mohtashemi et al.,
 Opt. Express **29**, 4912 (2021)](https://doi.org/10.1364/OE.417724).

This is *beta* software that is currently under development.

| Information       | Links                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
|:------------------|:--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| **Project**       | [![Project Status: Active – The project has reached a stable, usable state and is being actively developed.](https://www.repostatus.org/badges/latest/active.svg)](https://www.repostatus.org/#active) ![GitHub](https://img.shields.io/github/license/dodge-research-group/thztools) ![PyPI - Status](https://img.shields.io/pypi/status/thztools) ![PyPI - Version](https://img.shields.io/pypi/v/thztools) [![Anaconda-Server Badge](https://anaconda.org/conda-forge/thztools/badges/version.svg)](https://anaconda.org/conda-forge/thztools) ![PyPI - Python Version](https://img.shields.io/pypi/pyversions/thztools) [![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff) [![Common Changelog](https://common-changelog.org/badge.svg)](https://common-changelog.org) [![Contributor Covenant](https://img.shields.io/badge/Contributor%20Covenant-2.1-4baaaa.svg)](code_of_conduct.md) [![DOI](https://zenodo.org/badge/569133241.svg)](https://zenodo.org/doi/10.5281/zenodo.10100093) |
| **Build**         | ![GitHub Workflow Status](https://img.shields.io/github/actions/workflow/status/dodge-research-group/thztools/sphinx.yml?label=build%3Adocs) ![GitHub Workflow Status](https://img.shields.io/github/actions/workflow/status/dodge-research-group/thztools/pytest-with-coverage.yml?label=build%3Atests%20(conda)) ![GitHub Workflow Status](https://img.shields.io/github/actions/workflow/status/dodge-research-group/thztools/test-pip.yml?label=build%3Atests%20(pip)) [![codecov](https://codecov.io/gh/dodge-research-group/thztools/branch/dev/graph/badge.svg?token=U8PLKTQ7AH)](https://codecov.io/gh/dodge-research-group/thztools)                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| **Documentation** | https://dodge-research-group.github.io/thztools/                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| **Cite**          | L. Mohtashemi et al., *Opt. Express* **29**, 4912 (2021). [(DOI)](https://doi.org/10.1364/OE.417724)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |

The original MATLAB code is available at [Zenodo](https://zenodo.org/record/4876388).

## Installation

You can install THzTools with `pip`:

```shell
pip install thztools
```

THzTools is also available through `conda-forge`:

```shell
conda install -c conda-forge thztools
```

See the [Getting started](https://dodge-research-group.github.io/thztools/getting_started.html) tutorial for additional information.

## Usage

In the conventional approach to THz-TDS analysis, one transforms
the time-domain measurements into the frequency domain for further analysis.
This approach has well-known problems, however, which can be resolved by
using a maximum-likelihood estimation procedure in the time 
domain. To support this mode of analysis, the `THzTools`
package provides functionality and documentation that are unavailable in
existing THz-TDS analysis software. It provides functions to simulate THz-TDS
measurements (eg, [`timebase`](https://dodge-research-group.github.io/thztools/generated/thztools.timebase.html)
and [`wave`](https://dodge-research-group.github.io/thztools/generated/thztools.wave.html)), 
apply a frequency response function to a THz-TDS waveform ([`apply_frf`](https://dodge-research-group.github.io/thztools/generated/thztools.apply_frf.html)),
characterize the noise of a THz-TDS system ([`noisefit`](https://dodge-research-group.github.io/thztools/generated/thztools.noisefit.html)),
and fit a parameterized frequency response function to a pair of input and
output waveforms ([`fit`](https://dodge-research-group.github.io/thztools/generated/thztools.fit.html)).

With THzTools, you can:
- [Simulate a terahertz waveform](https://dodge-research-group.github.io/thztools/examples/simulate-waveform.html)
- [Simulate realistic time-domain noise for a waveform](https://dodge-research-group.github.io/thztools/examples/simulate-noise.html)
- [Apply a frequency response function (FRF) to a time-domain waveform](https://dodge-research-group.github.io/thztools/examples/apply-frequency-response.html)
- [Rescale and shift a waveform](https://dodge-research-group.github.io/thztools/examples/rescale-and-shift-waveform.html#)
- [Estimate time-domain system noise parameters from a set of measured waveforms](https://dodge-research-group.github.io/thztools/examples/estimate-noise.html)
- [Fit a parameterized FRF to a pair of time-domain waveforms](https://dodge-research-group.github.io/thztools/examples/fit-with-frf.html)

For example, the following code creates an ideal waveform and applies a
frequency response function to it.

```python
import numpy as np
import thztools as thz

# Set the waveform parameters
n = 256  # Number of samples
dt = 0.05  # Sampling time [ps]
a = 0.5 # Scale factor
eta = 1.0 # Delay [ps]

# Simulate the waveform
t = thz.timebase(n, dt=dt)
mu = thz.wave(n, dt=dt)

# Define a frequency response function
def frfun(omega, _a, _eta):
    return _a * np.exp(-1j * omega * _eta)

# Apply the frequency response function to the waveform
psi = thz.apply_frf(frfun, mu, dt=dt, args=(a, eta))
```

## Citation

If you use THzTools, please consider citing the **paper** and/or the **software
package**.

### Paper
```shell
@article{Mohtashemi:21,
author = {Laleh Mohtashemi and Paul Westlund and Derek G. Sahota and 
Graham B. Lea and Ian Bushfield and Payam Mousavi and J. Steven Dodge},
journal = {Opt. Express},
number = {4},
pages = {4912--4926},
publisher = {Optica Publishing Group},
title = {Maximum-likelihood parameter estimation in terahertz time-domain 
spectroscopy},
volume = {29},
month = {Feb},
year = {2021},
url = {https://opg.optica.org/oe/abstract.cfm?URI=oe-29-4-4912},
doi = {10.1364/OE.417724},
}
```

### Software Package
```shell
@software{Posada_Loaiza_THzTools_2024,
author = {Posada Loaiza, Jonathan and Higuera-Quintero, Santiago and Noori, 
Alireza and Mohtashemi, Laleh and Hall, R. P. and Yimam, Naod Ayalew and 
Dodge, J. Steven},
license = {MIT},
month = oct,
title = {{THzTools}},
url = {https://github.com/dodge-research-group/thztools},
version = {0.5.3},
year = {2024}
}
```
