MatSciKit-COSMOTIM 0.2.2__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.
- matscikit_cosmotim-0.2.2/LICENSE +21 -0
- matscikit_cosmotim-0.2.2/PKG-INFO +299 -0
- matscikit_cosmotim-0.2.2/README.md +261 -0
- matscikit_cosmotim-0.2.2/pyproject.toml +105 -0
- matscikit_cosmotim-0.2.2/setup.cfg +4 -0
- matscikit_cosmotim-0.2.2/src/MatSciKit_COSMOTIM/__init__.py +19 -0
- matscikit_cosmotim-0.2.2/src/MatSciKit_COSMOTIM/constants.py +25 -0
- matscikit_cosmotim-0.2.2/src/MatSciKit_COSMOTIM/fitting/__init__.py +13 -0
- matscikit_cosmotim-0.2.2/src/MatSciKit_COSMOTIM/fitting/linear.py +67 -0
- matscikit_cosmotim-0.2.2/src/MatSciKit_COSMOTIM/heat_capacity/__init__.py +15 -0
- matscikit_cosmotim-0.2.2/src/MatSciKit_COSMOTIM/heat_capacity/debye.py +61 -0
- matscikit_cosmotim-0.2.2/src/MatSciKit_COSMOTIM/heat_capacity/dulong_petit.py +38 -0
- matscikit_cosmotim-0.2.2/src/MatSciKit_COSMOTIM/heat_capacity/low_t_fitting.py +154 -0
- matscikit_cosmotim-0.2.2/src/MatSciKit_COSMOTIM/io/__init__.py +36 -0
- matscikit_cosmotim-0.2.2/src/MatSciKit_COSMOTIM/io/dsc.py +59 -0
- matscikit_cosmotim-0.2.2/src/MatSciKit_COSMOTIM/io/lfa.py +49 -0
- matscikit_cosmotim-0.2.2/src/MatSciKit_COSMOTIM/io/lfa_excel.py +116 -0
- matscikit_cosmotim-0.2.2/src/MatSciKit_COSMOTIM/io/ppms_hc.py +76 -0
- matscikit_cosmotim-0.2.2/src/MatSciKit_COSMOTIM/io/ppms_tto.py +81 -0
- matscikit_cosmotim-0.2.2/src/MatSciKit_COSMOTIM/io/readers.py +387 -0
- matscikit_cosmotim-0.2.2/src/MatSciKit_COSMOTIM/py.typed +0 -0
- matscikit_cosmotim-0.2.2/src/MatSciKit_COSMOTIM/structure/__init__.py +17 -0
- matscikit_cosmotim-0.2.2/src/MatSciKit_COSMOTIM/structure/cif_reader.py +426 -0
- matscikit_cosmotim-0.2.2/src/MatSciKit_COSMOTIM/structure/material.py +730 -0
- matscikit_cosmotim-0.2.2/src/MatSciKit_COSMOTIM/structure/xrd_plot.py +184 -0
- matscikit_cosmotim-0.2.2/src/MatSciKit_COSMOTIM/structure/xrd_reader.py +88 -0
- matscikit_cosmotim-0.2.2/src/MatSciKit_COSMOTIM/thermal_conductivity/__init__.py +25 -0
- matscikit_cosmotim-0.2.2/src/MatSciKit_COSMOTIM/thermal_conductivity/cahill.py +148 -0
- matscikit_cosmotim-0.2.2/src/MatSciKit_COSMOTIM/thermal_conductivity/gruneisen.py +64 -0
- matscikit_cosmotim-0.2.2/src/MatSciKit_COSMOTIM/thermal_conductivity/lfa_dsc.py +101 -0
- matscikit_cosmotim-0.2.2/src/MatSciKit_COSMOTIM/thermal_conductivity/mean_free_path.py +99 -0
- matscikit_cosmotim-0.2.2/src/MatSciKit_COSMOTIM/thermal_conductivity/pipeline.py +262 -0
- matscikit_cosmotim-0.2.2/src/MatSciKit_COSMOTIM/thermal_conductivity/porosity_correction.py +57 -0
- matscikit_cosmotim-0.2.2/src/MatSciKit_COSMOTIM/tui/__init__.py +3 -0
- matscikit_cosmotim-0.2.2/src/MatSciKit_COSMOTIM/tui/__main__.py +8 -0
- matscikit_cosmotim-0.2.2/src/MatSciKit_COSMOTIM/tui/app.py +879 -0
- matscikit_cosmotim-0.2.2/src/MatSciKit_COSMOTIM/visualization/__init__.py +15 -0
- matscikit_cosmotim-0.2.2/src/MatSciKit_COSMOTIM/visualization/inset_style.py +99 -0
- matscikit_cosmotim-0.2.2/src/MatSciKit_COSMOTIM/visualization/journal_style.py +106 -0
- matscikit_cosmotim-0.2.2/src/MatSciKit_COSMOTIM/visualization/thermal_conductivity.py +252 -0
- matscikit_cosmotim-0.2.2/src/MatSciKit_COSMOTIM.egg-info/PKG-INFO +299 -0
- matscikit_cosmotim-0.2.2/src/MatSciKit_COSMOTIM.egg-info/SOURCES.txt +46 -0
- matscikit_cosmotim-0.2.2/src/MatSciKit_COSMOTIM.egg-info/dependency_links.txt +1 -0
- matscikit_cosmotim-0.2.2/src/MatSciKit_COSMOTIM.egg-info/entry_points.txt +2 -0
- matscikit_cosmotim-0.2.2/src/MatSciKit_COSMOTIM.egg-info/requires.txt +15 -0
- matscikit_cosmotim-0.2.2/src/MatSciKit_COSMOTIM.egg-info/top_level.txt +1 -0
- matscikit_cosmotim-0.2.2/tests/test_cif_reader.py +252 -0
- matscikit_cosmotim-0.2.2/tests/test_material.py +368 -0
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2025 Y. Wang
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
|
@@ -0,0 +1,299 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: MatSciKit-COSMOTIM
|
|
3
|
+
Version: 0.2.2
|
|
4
|
+
Summary: Python toolkit for materials science thermal property analysis
|
|
5
|
+
Author-email: Yitian Wang <ywang1057@ucr.edu>
|
|
6
|
+
License: MIT
|
|
7
|
+
Project-URL: Homepage, https://github.com/cosmotim/MatSciKit
|
|
8
|
+
Project-URL: Repository, https://github.com/cosmotim/MatSciKit
|
|
9
|
+
Project-URL: Issues, https://github.com/cosmotim/MatSciKit/issues
|
|
10
|
+
Keywords: materials-science,thermal-conductivity,heat-capacity,debye-temperature,phonon
|
|
11
|
+
Classifier: Development Status :: 3 - Alpha
|
|
12
|
+
Classifier: Intended Audience :: Science/Research
|
|
13
|
+
Classifier: Topic :: Scientific/Engineering :: Physics
|
|
14
|
+
Classifier: Topic :: Scientific/Engineering :: Chemistry
|
|
15
|
+
Classifier: Programming Language :: Python :: 3
|
|
16
|
+
Classifier: Programming Language :: Python :: 3.8
|
|
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: Programming Language :: Python :: 3.13
|
|
22
|
+
Requires-Python: >=3.8
|
|
23
|
+
Description-Content-Type: text/markdown
|
|
24
|
+
License-File: LICENSE
|
|
25
|
+
Requires-Dist: numpy
|
|
26
|
+
Requires-Dist: scipy
|
|
27
|
+
Requires-Dist: matplotlib
|
|
28
|
+
Provides-Extra: tui
|
|
29
|
+
Requires-Dist: textual>=0.40.0; extra == "tui"
|
|
30
|
+
Provides-Extra: excel
|
|
31
|
+
Requires-Dist: openpyxl>=3.0.0; extra == "excel"
|
|
32
|
+
Provides-Extra: dev
|
|
33
|
+
Requires-Dist: pytest; extra == "dev"
|
|
34
|
+
Requires-Dist: pytest-cov; extra == "dev"
|
|
35
|
+
Requires-Dist: build; extra == "dev"
|
|
36
|
+
Requires-Dist: twine; extra == "dev"
|
|
37
|
+
Dynamic: license-file
|
|
38
|
+
|
|
39
|
+
# MatSciKit
|
|
40
|
+
|
|
41
|
+
A Python toolkit for materials science research data processing, with a focus on thermal transport analysis.
|
|
42
|
+
|
|
43
|
+
[](https://www.python.org/downloads/)
|
|
44
|
+
[](LICENSE)
|
|
45
|
+
|
|
46
|
+
## Overview
|
|
47
|
+
|
|
48
|
+
MatSciKit provides a modular pipeline for analyzing thermal properties of materials, from raw instrument data to publication-ready results. It was designed to replace a collection of MATLAB scripts used in thermal transport research on solid-state ionic conductors and functional oxides.
|
|
49
|
+
|
|
50
|
+
### Three-Pipeline Architecture
|
|
51
|
+
|
|
52
|
+
```
|
|
53
|
+
Pipeline 0: Structure (XRD + CIF) → Material properties (V, ρ, N/V)
|
|
54
|
+
↓
|
|
55
|
+
Pipeline 1: Heat Capacity (Cp) → Debye temperature (θ_D), sound velocity (v_s)
|
|
56
|
+
↓
|
|
57
|
+
Pipeline 2: Thermal Conductivity → κ_solid, κ_min (Cahill), mean free path
|
|
58
|
+
```
|
|
59
|
+
|
|
60
|
+
## Installation
|
|
61
|
+
|
|
62
|
+
### From PyPI (recommended)
|
|
63
|
+
|
|
64
|
+
```bash
|
|
65
|
+
pip install matscikit-cosmotim
|
|
66
|
+
```
|
|
67
|
+
|
|
68
|
+
With interactive terminal interface:
|
|
69
|
+
```bash
|
|
70
|
+
pip install "matscikit-cosmotim[tui]"
|
|
71
|
+
```
|
|
72
|
+
|
|
73
|
+
### From GitHub (latest development version)
|
|
74
|
+
|
|
75
|
+
```bash
|
|
76
|
+
pip install git+https://github.com/cosmotim/MatSciKit.git
|
|
77
|
+
```
|
|
78
|
+
|
|
79
|
+
### For Development
|
|
80
|
+
|
|
81
|
+
```bash
|
|
82
|
+
git clone https://github.com/cosmotim/MatSciKit.git
|
|
83
|
+
cd MatSciKit
|
|
84
|
+
pip install -e ".[dev,tui]"
|
|
85
|
+
```
|
|
86
|
+
|
|
87
|
+
### Dependencies
|
|
88
|
+
|
|
89
|
+
- **NumPy** — array operations and linear algebra
|
|
90
|
+
- **SciPy** — numerical integration and curve fitting
|
|
91
|
+
- **Matplotlib** — publication-quality figure export
|
|
92
|
+
|
|
93
|
+
## Quick Start
|
|
94
|
+
|
|
95
|
+
### Pipeline 1: Heat Capacity Analysis
|
|
96
|
+
|
|
97
|
+
Extract Debye temperature and sound velocity from low-temperature heat capacity data:
|
|
98
|
+
|
|
99
|
+
```python
|
|
100
|
+
import numpy as np
|
|
101
|
+
from MatSciKit_COSMOTIM.io import ppms_hc, dsc
|
|
102
|
+
from MatSciKit_COSMOTIM.heat_capacity import low_t_fitting, dulong_petit
|
|
103
|
+
|
|
104
|
+
# Load PPMS heat capacity data
|
|
105
|
+
hc_data = np.loadtxt("LSHT_Cp_all.csv", delimiter=",")
|
|
106
|
+
T, Cp, Cp_err = hc_data[:, 0], hc_data[:, 1], hc_data[:, 2]
|
|
107
|
+
|
|
108
|
+
# Material parameters
|
|
109
|
+
V = 3.98**3 * 1e-30 # unit cell volume (m³)
|
|
110
|
+
N = 3/8 + 7/16 + 1/4 + 3/4 + 3 # atoms per unit cell
|
|
111
|
+
n_density = N / V # number density (atoms/m³)
|
|
112
|
+
density = 6870 # mass density (kg/m³)
|
|
113
|
+
|
|
114
|
+
# Fit low-T region: Cp/T vs T²
|
|
115
|
+
# Method 1: by temperature range
|
|
116
|
+
theta_D, v_s, err_D, err_v = low_t_fitting.fit(
|
|
117
|
+
T, Cp, Cp_err, n_density, density,
|
|
118
|
+
t_range=(3.0, 10.0)
|
|
119
|
+
)
|
|
120
|
+
|
|
121
|
+
# Method 2: by index range (1-based, like MATLAB)
|
|
122
|
+
theta_D, v_s, err_D, err_v = low_t_fitting.fit(
|
|
123
|
+
T, Cp, Cp_err, n_density, density,
|
|
124
|
+
n_range=(13, 41)
|
|
125
|
+
)
|
|
126
|
+
|
|
127
|
+
print(f"Debye temperature: {theta_D:.1f} ± {err_D:.1f} K")
|
|
128
|
+
print(f"Sound velocity: {v_s:.1f} ± {err_v:.1f} m/s")
|
|
129
|
+
|
|
130
|
+
# Dulong-Petit limit
|
|
131
|
+
dp_limit = dulong_petit.calculate(n_density, density)
|
|
132
|
+
print(f"Dulong-Petit limit: {dp_limit:.4f} J/(g·K)")
|
|
133
|
+
```
|
|
134
|
+
|
|
135
|
+
### Pipeline 2: Thermal Conductivity Analysis
|
|
136
|
+
|
|
137
|
+
Compute Cahill minimum thermal conductivity, porosity correction, and mean free path:
|
|
138
|
+
|
|
139
|
+
```python
|
|
140
|
+
from MatSciKit_COSMOTIM.io import ppms_tto, lfa
|
|
141
|
+
from MatSciKit_COSMOTIM.thermal_conductivity import (
|
|
142
|
+
cahill, mean_free_path, porosity_correction
|
|
143
|
+
)
|
|
144
|
+
|
|
145
|
+
# Load TTO data, dropping bad temperature points
|
|
146
|
+
tto_data = ppms_tto.read("sample_TTO.dat", drop_temps=[302, 303])
|
|
147
|
+
T_tto, kappa, kappa_err = tto_data[:, 0], tto_data[:, 1], tto_data[:, 2]
|
|
148
|
+
|
|
149
|
+
# Porosity correction: κ_solid from measured κ
|
|
150
|
+
kappa_solid = porosity_correction.correct(kappa, porosity=0.03)
|
|
151
|
+
|
|
152
|
+
# Cahill minimum thermal conductivity
|
|
153
|
+
T_plot = np.linspace(1, 1000, 500)
|
|
154
|
+
kappa_min = cahill.minimum_tc(T_plot, n_density, theta_D, v_s)
|
|
155
|
+
|
|
156
|
+
# Mean free path
|
|
157
|
+
mfp = mean_free_path.calculate(T_tto, kappa, theta_D, v_s)
|
|
158
|
+
```
|
|
159
|
+
|
|
160
|
+
### LFA + DSC → Thermal Conductivity
|
|
161
|
+
|
|
162
|
+
When LFA measures diffusivity and DSC measures heat capacity:
|
|
163
|
+
|
|
164
|
+
```python
|
|
165
|
+
from MatSciKit_COSMOTIM.thermal_conductivity import lfa_dsc
|
|
166
|
+
|
|
167
|
+
# κ = Cp × α × ρ (with error propagation)
|
|
168
|
+
tc_data, cp_avg = lfa_dsc.calculate(
|
|
169
|
+
cp_T, cp, cp_error, # DSC heat capacity
|
|
170
|
+
diff_T, diffusivity, diff_error, # LFA diffusivity
|
|
171
|
+
density=6.87, density_error=0.28
|
|
172
|
+
)
|
|
173
|
+
# tc_data columns: [Temperature, κ, κ_error]
|
|
174
|
+
```
|
|
175
|
+
|
|
176
|
+
### Visualization
|
|
177
|
+
|
|
178
|
+
Export publication-ready figures:
|
|
179
|
+
|
|
180
|
+
```python
|
|
181
|
+
from MatSciKit_COSMOTIM.visualization.journal_style import export_journal_figure
|
|
182
|
+
from MatSciKit_COSMOTIM.visualization.inset_style import export_inset_figure
|
|
183
|
+
|
|
184
|
+
import matplotlib.pyplot as plt
|
|
185
|
+
|
|
186
|
+
fig, ax = plt.subplots()
|
|
187
|
+
ax.plot(T, kappa, 'o')
|
|
188
|
+
ax.set_xlabel("T (K)")
|
|
189
|
+
ax.set_ylabel("κ (W m⁻¹ K⁻¹)")
|
|
190
|
+
|
|
191
|
+
# Export with journal formatting (Arial 11pt, 600 DPI, inward ticks)
|
|
192
|
+
export_journal_figure(fig, "thermal_conductivity", format="png")
|
|
193
|
+
```
|
|
194
|
+
|
|
195
|
+
## Package Structure
|
|
196
|
+
|
|
197
|
+
```
|
|
198
|
+
src/MatSciKit_COSMOTIM/
|
|
199
|
+
├── constants.py # Physical constants (kb, h, ħ)
|
|
200
|
+
├── io/ # Instrument data readers
|
|
201
|
+
│ ├── ppms_tto.py # PPMS Thermal Transport Option
|
|
202
|
+
│ ├── ppms_hc.py # PPMS Heat Capacity
|
|
203
|
+
│ ├── dsc.py # Differential Scanning Calorimetry
|
|
204
|
+
│ └── lfa.py # Laser Flash Analysis
|
|
205
|
+
├── structure/ # Crystallography & XRD (Pipeline 0)
|
|
206
|
+
│ ├── xrd_reader.py # XRD data file reader
|
|
207
|
+
│ └── xrd_plot.py # Multi-pattern XRD plotter
|
|
208
|
+
├── heat_capacity/ # Pipeline 1
|
|
209
|
+
│ ├── low_t_fitting.py # Debye T & v_s from Cp/T vs T²
|
|
210
|
+
│ ├── dulong_petit.py # Classical heat capacity limit
|
|
211
|
+
│ └── debye.py # θ_D from velocity or modulus
|
|
212
|
+
├── thermal_conductivity/ # Pipeline 2
|
|
213
|
+
│ ├── cahill.py # Cahill minimum κ model
|
|
214
|
+
│ ├── mean_free_path.py # Phonon MFP from κ
|
|
215
|
+
│ ├── porosity_correction.py # Solid κ from porous samples
|
|
216
|
+
│ ├── lfa_dsc.py # κ = Cp × α × ρ
|
|
217
|
+
│ └── gruneisen.py # Grüneisen parameter
|
|
218
|
+
├── fitting/ # Curve fitting utilities
|
|
219
|
+
│ └── linear.py # Weighted linear regression
|
|
220
|
+
└── visualization/ # Publication figures
|
|
221
|
+
├── journal_style.py # Journal figure formatting
|
|
222
|
+
└── inset_style.py # Inset panel formatting
|
|
223
|
+
```
|
|
224
|
+
|
|
225
|
+
## IO Readers
|
|
226
|
+
|
|
227
|
+
| Module | Instrument | Input Format | Output |
|
|
228
|
+
|--------|-----------|-------------|--------|
|
|
229
|
+
| `ppms_tto` | Quantum Design PPMS TTO | `.dat` file | [T, κ, κ_err] |
|
|
230
|
+
| `ppms_hc` | Quantum Design PPMS HC | `.dat` file | [T, Cp, Cp_err] |
|
|
231
|
+
| `dsc` | Netzsch DSC 214 | CSV export | [T(K), Cp] |
|
|
232
|
+
| `lfa` | Laser Flash Analysis | CSV | [T, value, error] |
|
|
233
|
+
|
|
234
|
+
## Interactive Terminal Interface
|
|
235
|
+
|
|
236
|
+
MatSciKit includes an interactive TUI for loading and analyzing data without writing code:
|
|
237
|
+
|
|
238
|
+
```bash
|
|
239
|
+
# Launch the TUI (requires tui extra)
|
|
240
|
+
pip install "matscikit-cosmotim[tui]"
|
|
241
|
+
matscikit
|
|
242
|
+
```
|
|
243
|
+
|
|
244
|
+
Features:
|
|
245
|
+
- File browser to select data files
|
|
246
|
+
- Auto-detection of PPMS HC, PPMS TTO, DSC, and LFA formats
|
|
247
|
+
- Loading progress and data preview
|
|
248
|
+
- Pipeline analysis selection
|
|
249
|
+
|
|
250
|
+
## Running Tests
|
|
251
|
+
|
|
252
|
+
```bash
|
|
253
|
+
# Run all tests
|
|
254
|
+
python -m pytest tests/ -v
|
|
255
|
+
|
|
256
|
+
# Run specific pipeline
|
|
257
|
+
python -m pytest tests/test_pipeline1.py -v
|
|
258
|
+
python -m pytest tests/test_pipeline2.py -v
|
|
259
|
+
```
|
|
260
|
+
|
|
261
|
+
## Roadmap
|
|
262
|
+
|
|
263
|
+
- [x] Pipeline 1: Heat capacity analysis
|
|
264
|
+
- [x] Pipeline 2: Thermal conductivity analysis
|
|
265
|
+
- [ ] Pipeline 0: CIF file reader for automated material properties
|
|
266
|
+
- [ ] Two-channel thermal conductivity fitting model
|
|
267
|
+
- [ ] XRDML file format support
|
|
268
|
+
- [ ] Example Jupyter notebooks
|
|
269
|
+
|
|
270
|
+
## Citation
|
|
271
|
+
|
|
272
|
+
If you use MatSciKit in your research, please cite:
|
|
273
|
+
|
|
274
|
+
```bibtex
|
|
275
|
+
@software{matscikit,
|
|
276
|
+
author = {Wang, Yitian},
|
|
277
|
+
title = {MatSciKit: Python Toolkit for Materials Science Research},
|
|
278
|
+
url = {https://github.com/cosmotim/MatSciKit},
|
|
279
|
+
year = {2026}
|
|
280
|
+
}
|
|
281
|
+
```
|
|
282
|
+
|
|
283
|
+
The methods implemented in this package are based on the following work:
|
|
284
|
+
|
|
285
|
+
```bibtex
|
|
286
|
+
@article{wang2025thermal,
|
|
287
|
+
title = {Origin of Intrinsically Low Thermal Conductivity in a Garnet-Type Solid Electrolyte},
|
|
288
|
+
author = {Wang, Yitian and Su, Yaokun and Carrete, Jes\'us and Zhang, Huanyu and Wu, Nan and Li, Yutao and Li, Hongze and He, Jiaming and Xu, Youming and Guo, Shucheng and Cai, Qingan and Abernathy, Douglas L. and Williams, Travis and Kravchyk, Kostiantyn V. and Kovalenko, Maksym V. and Madsen, Georg K.H. and Li, Chen and Chen, Xi},
|
|
289
|
+
journal = {PRX Energy},
|
|
290
|
+
volume = {4},
|
|
291
|
+
pages = {033004},
|
|
292
|
+
year = {2025},
|
|
293
|
+
doi = {10.1103/6wj2-kzhh}
|
|
294
|
+
}
|
|
295
|
+
```
|
|
296
|
+
|
|
297
|
+
## License
|
|
298
|
+
|
|
299
|
+
MIT License — see [LICENSE](LICENSE) for details.
|
|
@@ -0,0 +1,261 @@
|
|
|
1
|
+
# MatSciKit
|
|
2
|
+
|
|
3
|
+
A Python toolkit for materials science research data processing, with a focus on thermal transport analysis.
|
|
4
|
+
|
|
5
|
+
[](https://www.python.org/downloads/)
|
|
6
|
+
[](LICENSE)
|
|
7
|
+
|
|
8
|
+
## Overview
|
|
9
|
+
|
|
10
|
+
MatSciKit provides a modular pipeline for analyzing thermal properties of materials, from raw instrument data to publication-ready results. It was designed to replace a collection of MATLAB scripts used in thermal transport research on solid-state ionic conductors and functional oxides.
|
|
11
|
+
|
|
12
|
+
### Three-Pipeline Architecture
|
|
13
|
+
|
|
14
|
+
```
|
|
15
|
+
Pipeline 0: Structure (XRD + CIF) → Material properties (V, ρ, N/V)
|
|
16
|
+
↓
|
|
17
|
+
Pipeline 1: Heat Capacity (Cp) → Debye temperature (θ_D), sound velocity (v_s)
|
|
18
|
+
↓
|
|
19
|
+
Pipeline 2: Thermal Conductivity → κ_solid, κ_min (Cahill), mean free path
|
|
20
|
+
```
|
|
21
|
+
|
|
22
|
+
## Installation
|
|
23
|
+
|
|
24
|
+
### From PyPI (recommended)
|
|
25
|
+
|
|
26
|
+
```bash
|
|
27
|
+
pip install matscikit-cosmotim
|
|
28
|
+
```
|
|
29
|
+
|
|
30
|
+
With interactive terminal interface:
|
|
31
|
+
```bash
|
|
32
|
+
pip install "matscikit-cosmotim[tui]"
|
|
33
|
+
```
|
|
34
|
+
|
|
35
|
+
### From GitHub (latest development version)
|
|
36
|
+
|
|
37
|
+
```bash
|
|
38
|
+
pip install git+https://github.com/cosmotim/MatSciKit.git
|
|
39
|
+
```
|
|
40
|
+
|
|
41
|
+
### For Development
|
|
42
|
+
|
|
43
|
+
```bash
|
|
44
|
+
git clone https://github.com/cosmotim/MatSciKit.git
|
|
45
|
+
cd MatSciKit
|
|
46
|
+
pip install -e ".[dev,tui]"
|
|
47
|
+
```
|
|
48
|
+
|
|
49
|
+
### Dependencies
|
|
50
|
+
|
|
51
|
+
- **NumPy** — array operations and linear algebra
|
|
52
|
+
- **SciPy** — numerical integration and curve fitting
|
|
53
|
+
- **Matplotlib** — publication-quality figure export
|
|
54
|
+
|
|
55
|
+
## Quick Start
|
|
56
|
+
|
|
57
|
+
### Pipeline 1: Heat Capacity Analysis
|
|
58
|
+
|
|
59
|
+
Extract Debye temperature and sound velocity from low-temperature heat capacity data:
|
|
60
|
+
|
|
61
|
+
```python
|
|
62
|
+
import numpy as np
|
|
63
|
+
from MatSciKit_COSMOTIM.io import ppms_hc, dsc
|
|
64
|
+
from MatSciKit_COSMOTIM.heat_capacity import low_t_fitting, dulong_petit
|
|
65
|
+
|
|
66
|
+
# Load PPMS heat capacity data
|
|
67
|
+
hc_data = np.loadtxt("LSHT_Cp_all.csv", delimiter=",")
|
|
68
|
+
T, Cp, Cp_err = hc_data[:, 0], hc_data[:, 1], hc_data[:, 2]
|
|
69
|
+
|
|
70
|
+
# Material parameters
|
|
71
|
+
V = 3.98**3 * 1e-30 # unit cell volume (m³)
|
|
72
|
+
N = 3/8 + 7/16 + 1/4 + 3/4 + 3 # atoms per unit cell
|
|
73
|
+
n_density = N / V # number density (atoms/m³)
|
|
74
|
+
density = 6870 # mass density (kg/m³)
|
|
75
|
+
|
|
76
|
+
# Fit low-T region: Cp/T vs T²
|
|
77
|
+
# Method 1: by temperature range
|
|
78
|
+
theta_D, v_s, err_D, err_v = low_t_fitting.fit(
|
|
79
|
+
T, Cp, Cp_err, n_density, density,
|
|
80
|
+
t_range=(3.0, 10.0)
|
|
81
|
+
)
|
|
82
|
+
|
|
83
|
+
# Method 2: by index range (1-based, like MATLAB)
|
|
84
|
+
theta_D, v_s, err_D, err_v = low_t_fitting.fit(
|
|
85
|
+
T, Cp, Cp_err, n_density, density,
|
|
86
|
+
n_range=(13, 41)
|
|
87
|
+
)
|
|
88
|
+
|
|
89
|
+
print(f"Debye temperature: {theta_D:.1f} ± {err_D:.1f} K")
|
|
90
|
+
print(f"Sound velocity: {v_s:.1f} ± {err_v:.1f} m/s")
|
|
91
|
+
|
|
92
|
+
# Dulong-Petit limit
|
|
93
|
+
dp_limit = dulong_petit.calculate(n_density, density)
|
|
94
|
+
print(f"Dulong-Petit limit: {dp_limit:.4f} J/(g·K)")
|
|
95
|
+
```
|
|
96
|
+
|
|
97
|
+
### Pipeline 2: Thermal Conductivity Analysis
|
|
98
|
+
|
|
99
|
+
Compute Cahill minimum thermal conductivity, porosity correction, and mean free path:
|
|
100
|
+
|
|
101
|
+
```python
|
|
102
|
+
from MatSciKit_COSMOTIM.io import ppms_tto, lfa
|
|
103
|
+
from MatSciKit_COSMOTIM.thermal_conductivity import (
|
|
104
|
+
cahill, mean_free_path, porosity_correction
|
|
105
|
+
)
|
|
106
|
+
|
|
107
|
+
# Load TTO data, dropping bad temperature points
|
|
108
|
+
tto_data = ppms_tto.read("sample_TTO.dat", drop_temps=[302, 303])
|
|
109
|
+
T_tto, kappa, kappa_err = tto_data[:, 0], tto_data[:, 1], tto_data[:, 2]
|
|
110
|
+
|
|
111
|
+
# Porosity correction: κ_solid from measured κ
|
|
112
|
+
kappa_solid = porosity_correction.correct(kappa, porosity=0.03)
|
|
113
|
+
|
|
114
|
+
# Cahill minimum thermal conductivity
|
|
115
|
+
T_plot = np.linspace(1, 1000, 500)
|
|
116
|
+
kappa_min = cahill.minimum_tc(T_plot, n_density, theta_D, v_s)
|
|
117
|
+
|
|
118
|
+
# Mean free path
|
|
119
|
+
mfp = mean_free_path.calculate(T_tto, kappa, theta_D, v_s)
|
|
120
|
+
```
|
|
121
|
+
|
|
122
|
+
### LFA + DSC → Thermal Conductivity
|
|
123
|
+
|
|
124
|
+
When LFA measures diffusivity and DSC measures heat capacity:
|
|
125
|
+
|
|
126
|
+
```python
|
|
127
|
+
from MatSciKit_COSMOTIM.thermal_conductivity import lfa_dsc
|
|
128
|
+
|
|
129
|
+
# κ = Cp × α × ρ (with error propagation)
|
|
130
|
+
tc_data, cp_avg = lfa_dsc.calculate(
|
|
131
|
+
cp_T, cp, cp_error, # DSC heat capacity
|
|
132
|
+
diff_T, diffusivity, diff_error, # LFA diffusivity
|
|
133
|
+
density=6.87, density_error=0.28
|
|
134
|
+
)
|
|
135
|
+
# tc_data columns: [Temperature, κ, κ_error]
|
|
136
|
+
```
|
|
137
|
+
|
|
138
|
+
### Visualization
|
|
139
|
+
|
|
140
|
+
Export publication-ready figures:
|
|
141
|
+
|
|
142
|
+
```python
|
|
143
|
+
from MatSciKit_COSMOTIM.visualization.journal_style import export_journal_figure
|
|
144
|
+
from MatSciKit_COSMOTIM.visualization.inset_style import export_inset_figure
|
|
145
|
+
|
|
146
|
+
import matplotlib.pyplot as plt
|
|
147
|
+
|
|
148
|
+
fig, ax = plt.subplots()
|
|
149
|
+
ax.plot(T, kappa, 'o')
|
|
150
|
+
ax.set_xlabel("T (K)")
|
|
151
|
+
ax.set_ylabel("κ (W m⁻¹ K⁻¹)")
|
|
152
|
+
|
|
153
|
+
# Export with journal formatting (Arial 11pt, 600 DPI, inward ticks)
|
|
154
|
+
export_journal_figure(fig, "thermal_conductivity", format="png")
|
|
155
|
+
```
|
|
156
|
+
|
|
157
|
+
## Package Structure
|
|
158
|
+
|
|
159
|
+
```
|
|
160
|
+
src/MatSciKit_COSMOTIM/
|
|
161
|
+
├── constants.py # Physical constants (kb, h, ħ)
|
|
162
|
+
├── io/ # Instrument data readers
|
|
163
|
+
│ ├── ppms_tto.py # PPMS Thermal Transport Option
|
|
164
|
+
│ ├── ppms_hc.py # PPMS Heat Capacity
|
|
165
|
+
│ ├── dsc.py # Differential Scanning Calorimetry
|
|
166
|
+
│ └── lfa.py # Laser Flash Analysis
|
|
167
|
+
├── structure/ # Crystallography & XRD (Pipeline 0)
|
|
168
|
+
│ ├── xrd_reader.py # XRD data file reader
|
|
169
|
+
│ └── xrd_plot.py # Multi-pattern XRD plotter
|
|
170
|
+
├── heat_capacity/ # Pipeline 1
|
|
171
|
+
│ ├── low_t_fitting.py # Debye T & v_s from Cp/T vs T²
|
|
172
|
+
│ ├── dulong_petit.py # Classical heat capacity limit
|
|
173
|
+
│ └── debye.py # θ_D from velocity or modulus
|
|
174
|
+
├── thermal_conductivity/ # Pipeline 2
|
|
175
|
+
│ ├── cahill.py # Cahill minimum κ model
|
|
176
|
+
│ ├── mean_free_path.py # Phonon MFP from κ
|
|
177
|
+
│ ├── porosity_correction.py # Solid κ from porous samples
|
|
178
|
+
│ ├── lfa_dsc.py # κ = Cp × α × ρ
|
|
179
|
+
│ └── gruneisen.py # Grüneisen parameter
|
|
180
|
+
├── fitting/ # Curve fitting utilities
|
|
181
|
+
│ └── linear.py # Weighted linear regression
|
|
182
|
+
└── visualization/ # Publication figures
|
|
183
|
+
├── journal_style.py # Journal figure formatting
|
|
184
|
+
└── inset_style.py # Inset panel formatting
|
|
185
|
+
```
|
|
186
|
+
|
|
187
|
+
## IO Readers
|
|
188
|
+
|
|
189
|
+
| Module | Instrument | Input Format | Output |
|
|
190
|
+
|--------|-----------|-------------|--------|
|
|
191
|
+
| `ppms_tto` | Quantum Design PPMS TTO | `.dat` file | [T, κ, κ_err] |
|
|
192
|
+
| `ppms_hc` | Quantum Design PPMS HC | `.dat` file | [T, Cp, Cp_err] |
|
|
193
|
+
| `dsc` | Netzsch DSC 214 | CSV export | [T(K), Cp] |
|
|
194
|
+
| `lfa` | Laser Flash Analysis | CSV | [T, value, error] |
|
|
195
|
+
|
|
196
|
+
## Interactive Terminal Interface
|
|
197
|
+
|
|
198
|
+
MatSciKit includes an interactive TUI for loading and analyzing data without writing code:
|
|
199
|
+
|
|
200
|
+
```bash
|
|
201
|
+
# Launch the TUI (requires tui extra)
|
|
202
|
+
pip install "matscikit-cosmotim[tui]"
|
|
203
|
+
matscikit
|
|
204
|
+
```
|
|
205
|
+
|
|
206
|
+
Features:
|
|
207
|
+
- File browser to select data files
|
|
208
|
+
- Auto-detection of PPMS HC, PPMS TTO, DSC, and LFA formats
|
|
209
|
+
- Loading progress and data preview
|
|
210
|
+
- Pipeline analysis selection
|
|
211
|
+
|
|
212
|
+
## Running Tests
|
|
213
|
+
|
|
214
|
+
```bash
|
|
215
|
+
# Run all tests
|
|
216
|
+
python -m pytest tests/ -v
|
|
217
|
+
|
|
218
|
+
# Run specific pipeline
|
|
219
|
+
python -m pytest tests/test_pipeline1.py -v
|
|
220
|
+
python -m pytest tests/test_pipeline2.py -v
|
|
221
|
+
```
|
|
222
|
+
|
|
223
|
+
## Roadmap
|
|
224
|
+
|
|
225
|
+
- [x] Pipeline 1: Heat capacity analysis
|
|
226
|
+
- [x] Pipeline 2: Thermal conductivity analysis
|
|
227
|
+
- [ ] Pipeline 0: CIF file reader for automated material properties
|
|
228
|
+
- [ ] Two-channel thermal conductivity fitting model
|
|
229
|
+
- [ ] XRDML file format support
|
|
230
|
+
- [ ] Example Jupyter notebooks
|
|
231
|
+
|
|
232
|
+
## Citation
|
|
233
|
+
|
|
234
|
+
If you use MatSciKit in your research, please cite:
|
|
235
|
+
|
|
236
|
+
```bibtex
|
|
237
|
+
@software{matscikit,
|
|
238
|
+
author = {Wang, Yitian},
|
|
239
|
+
title = {MatSciKit: Python Toolkit for Materials Science Research},
|
|
240
|
+
url = {https://github.com/cosmotim/MatSciKit},
|
|
241
|
+
year = {2026}
|
|
242
|
+
}
|
|
243
|
+
```
|
|
244
|
+
|
|
245
|
+
The methods implemented in this package are based on the following work:
|
|
246
|
+
|
|
247
|
+
```bibtex
|
|
248
|
+
@article{wang2025thermal,
|
|
249
|
+
title = {Origin of Intrinsically Low Thermal Conductivity in a Garnet-Type Solid Electrolyte},
|
|
250
|
+
author = {Wang, Yitian and Su, Yaokun and Carrete, Jes\'us and Zhang, Huanyu and Wu, Nan and Li, Yutao and Li, Hongze and He, Jiaming and Xu, Youming and Guo, Shucheng and Cai, Qingan and Abernathy, Douglas L. and Williams, Travis and Kravchyk, Kostiantyn V. and Kovalenko, Maksym V. and Madsen, Georg K.H. and Li, Chen and Chen, Xi},
|
|
251
|
+
journal = {PRX Energy},
|
|
252
|
+
volume = {4},
|
|
253
|
+
pages = {033004},
|
|
254
|
+
year = {2025},
|
|
255
|
+
doi = {10.1103/6wj2-kzhh}
|
|
256
|
+
}
|
|
257
|
+
```
|
|
258
|
+
|
|
259
|
+
## License
|
|
260
|
+
|
|
261
|
+
MIT License — see [LICENSE](LICENSE) for details.
|
|
@@ -0,0 +1,105 @@
|
|
|
1
|
+
[build-system]
|
|
2
|
+
requires = ["setuptools>=61.0", "wheel"]
|
|
3
|
+
build-backend = "setuptools.build_meta"
|
|
4
|
+
|
|
5
|
+
[project]
|
|
6
|
+
name = "MatSciKit-COSMOTIM"
|
|
7
|
+
version = "0.2.2"
|
|
8
|
+
description = "Python toolkit for materials science thermal property analysis"
|
|
9
|
+
readme = "README.md"
|
|
10
|
+
requires-python = ">=3.8"
|
|
11
|
+
license = {text = "MIT"}
|
|
12
|
+
authors = [
|
|
13
|
+
{name = "Yitian Wang", email = "ywang1057@ucr.edu"}
|
|
14
|
+
]
|
|
15
|
+
keywords = [
|
|
16
|
+
"materials-science",
|
|
17
|
+
"thermal-conductivity",
|
|
18
|
+
"heat-capacity",
|
|
19
|
+
"debye-temperature",
|
|
20
|
+
"phonon",
|
|
21
|
+
]
|
|
22
|
+
classifiers = [
|
|
23
|
+
"Development Status :: 3 - Alpha",
|
|
24
|
+
"Intended Audience :: Science/Research",
|
|
25
|
+
"Topic :: Scientific/Engineering :: Physics",
|
|
26
|
+
"Topic :: Scientific/Engineering :: Chemistry",
|
|
27
|
+
"Programming Language :: Python :: 3",
|
|
28
|
+
"Programming Language :: Python :: 3.8",
|
|
29
|
+
"Programming Language :: Python :: 3.9",
|
|
30
|
+
"Programming Language :: Python :: 3.10",
|
|
31
|
+
"Programming Language :: Python :: 3.11",
|
|
32
|
+
"Programming Language :: Python :: 3.12",
|
|
33
|
+
"Programming Language :: Python :: 3.13",
|
|
34
|
+
]
|
|
35
|
+
dependencies = [
|
|
36
|
+
"numpy",
|
|
37
|
+
"scipy",
|
|
38
|
+
"matplotlib",
|
|
39
|
+
]
|
|
40
|
+
|
|
41
|
+
[project.scripts]
|
|
42
|
+
matscikit = "MatSciKit_COSMOTIM.tui.app:main"
|
|
43
|
+
|
|
44
|
+
[project.optional-dependencies]
|
|
45
|
+
tui = [
|
|
46
|
+
"textual>=0.40.0",
|
|
47
|
+
]
|
|
48
|
+
excel = [
|
|
49
|
+
"openpyxl>=3.0.0",
|
|
50
|
+
]
|
|
51
|
+
dev = [
|
|
52
|
+
"pytest",
|
|
53
|
+
"pytest-cov",
|
|
54
|
+
"build",
|
|
55
|
+
"twine",
|
|
56
|
+
]
|
|
57
|
+
|
|
58
|
+
[tool.ruff]
|
|
59
|
+
line-length = 100
|
|
60
|
+
target-version = "py38"
|
|
61
|
+
|
|
62
|
+
[tool.ruff.lint]
|
|
63
|
+
select = [
|
|
64
|
+
"E", # pycodestyle errors
|
|
65
|
+
"F", # pyflakes
|
|
66
|
+
"I", # isort
|
|
67
|
+
"UP", # pyupgrade
|
|
68
|
+
"D", # pydocstyle
|
|
69
|
+
"B", # flake8-bugbear
|
|
70
|
+
"SIM", # flake8-simplify
|
|
71
|
+
"RUF", # ruff-specific rules
|
|
72
|
+
]
|
|
73
|
+
ignore = [
|
|
74
|
+
"D100", # Missing docstring in public module (we have them, but not all)
|
|
75
|
+
"D102", # Missing docstring in public method (TUI event handlers)
|
|
76
|
+
"D104", # Missing docstring in public package
|
|
77
|
+
"D105", # Missing docstring in magic method
|
|
78
|
+
"D212", # Multi-line docstring summary should start at first line
|
|
79
|
+
"D203", # One blank line before class docstring (conflicts with D211)
|
|
80
|
+
"D401", # Imperative mood (scientific function names are descriptive)
|
|
81
|
+
"RUF001", # Ambiguous unicode in strings — intentional (en dash, etc.)
|
|
82
|
+
"RUF002", # Ambiguous unicode in docstrings — intentional (Greek letters: γ, ρ, α)
|
|
83
|
+
"RUF003", # Ambiguous unicode in comments — intentional (scientific notation)
|
|
84
|
+
"RUF012", # Mutable class defaults — expected pattern for Textual widgets
|
|
85
|
+
]
|
|
86
|
+
|
|
87
|
+
[tool.ruff.lint.pydocstyle]
|
|
88
|
+
convention = "numpy"
|
|
89
|
+
|
|
90
|
+
[tool.ruff.lint.per-file-ignores]
|
|
91
|
+
"tests/**" = ["D101", "SIM115"]
|
|
92
|
+
|
|
93
|
+
[tool.ruff.lint.isort]
|
|
94
|
+
known-first-party = ["MatSciKit_COSMOTIM"]
|
|
95
|
+
|
|
96
|
+
[tool.setuptools.packages.find]
|
|
97
|
+
where = ["src"]
|
|
98
|
+
|
|
99
|
+
[tool.setuptools.package-data]
|
|
100
|
+
MatSciKit_COSMOTIM = ["py.typed"]
|
|
101
|
+
|
|
102
|
+
[project.urls]
|
|
103
|
+
Homepage = "https://github.com/cosmotim/MatSciKit"
|
|
104
|
+
Repository = "https://github.com/cosmotim/MatSciKit"
|
|
105
|
+
Issues = "https://github.com/cosmotim/MatSciKit/issues"
|