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.
Files changed (48) hide show
  1. matscikit_cosmotim-0.2.2/LICENSE +21 -0
  2. matscikit_cosmotim-0.2.2/PKG-INFO +299 -0
  3. matscikit_cosmotim-0.2.2/README.md +261 -0
  4. matscikit_cosmotim-0.2.2/pyproject.toml +105 -0
  5. matscikit_cosmotim-0.2.2/setup.cfg +4 -0
  6. matscikit_cosmotim-0.2.2/src/MatSciKit_COSMOTIM/__init__.py +19 -0
  7. matscikit_cosmotim-0.2.2/src/MatSciKit_COSMOTIM/constants.py +25 -0
  8. matscikit_cosmotim-0.2.2/src/MatSciKit_COSMOTIM/fitting/__init__.py +13 -0
  9. matscikit_cosmotim-0.2.2/src/MatSciKit_COSMOTIM/fitting/linear.py +67 -0
  10. matscikit_cosmotim-0.2.2/src/MatSciKit_COSMOTIM/heat_capacity/__init__.py +15 -0
  11. matscikit_cosmotim-0.2.2/src/MatSciKit_COSMOTIM/heat_capacity/debye.py +61 -0
  12. matscikit_cosmotim-0.2.2/src/MatSciKit_COSMOTIM/heat_capacity/dulong_petit.py +38 -0
  13. matscikit_cosmotim-0.2.2/src/MatSciKit_COSMOTIM/heat_capacity/low_t_fitting.py +154 -0
  14. matscikit_cosmotim-0.2.2/src/MatSciKit_COSMOTIM/io/__init__.py +36 -0
  15. matscikit_cosmotim-0.2.2/src/MatSciKit_COSMOTIM/io/dsc.py +59 -0
  16. matscikit_cosmotim-0.2.2/src/MatSciKit_COSMOTIM/io/lfa.py +49 -0
  17. matscikit_cosmotim-0.2.2/src/MatSciKit_COSMOTIM/io/lfa_excel.py +116 -0
  18. matscikit_cosmotim-0.2.2/src/MatSciKit_COSMOTIM/io/ppms_hc.py +76 -0
  19. matscikit_cosmotim-0.2.2/src/MatSciKit_COSMOTIM/io/ppms_tto.py +81 -0
  20. matscikit_cosmotim-0.2.2/src/MatSciKit_COSMOTIM/io/readers.py +387 -0
  21. matscikit_cosmotim-0.2.2/src/MatSciKit_COSMOTIM/py.typed +0 -0
  22. matscikit_cosmotim-0.2.2/src/MatSciKit_COSMOTIM/structure/__init__.py +17 -0
  23. matscikit_cosmotim-0.2.2/src/MatSciKit_COSMOTIM/structure/cif_reader.py +426 -0
  24. matscikit_cosmotim-0.2.2/src/MatSciKit_COSMOTIM/structure/material.py +730 -0
  25. matscikit_cosmotim-0.2.2/src/MatSciKit_COSMOTIM/structure/xrd_plot.py +184 -0
  26. matscikit_cosmotim-0.2.2/src/MatSciKit_COSMOTIM/structure/xrd_reader.py +88 -0
  27. matscikit_cosmotim-0.2.2/src/MatSciKit_COSMOTIM/thermal_conductivity/__init__.py +25 -0
  28. matscikit_cosmotim-0.2.2/src/MatSciKit_COSMOTIM/thermal_conductivity/cahill.py +148 -0
  29. matscikit_cosmotim-0.2.2/src/MatSciKit_COSMOTIM/thermal_conductivity/gruneisen.py +64 -0
  30. matscikit_cosmotim-0.2.2/src/MatSciKit_COSMOTIM/thermal_conductivity/lfa_dsc.py +101 -0
  31. matscikit_cosmotim-0.2.2/src/MatSciKit_COSMOTIM/thermal_conductivity/mean_free_path.py +99 -0
  32. matscikit_cosmotim-0.2.2/src/MatSciKit_COSMOTIM/thermal_conductivity/pipeline.py +262 -0
  33. matscikit_cosmotim-0.2.2/src/MatSciKit_COSMOTIM/thermal_conductivity/porosity_correction.py +57 -0
  34. matscikit_cosmotim-0.2.2/src/MatSciKit_COSMOTIM/tui/__init__.py +3 -0
  35. matscikit_cosmotim-0.2.2/src/MatSciKit_COSMOTIM/tui/__main__.py +8 -0
  36. matscikit_cosmotim-0.2.2/src/MatSciKit_COSMOTIM/tui/app.py +879 -0
  37. matscikit_cosmotim-0.2.2/src/MatSciKit_COSMOTIM/visualization/__init__.py +15 -0
  38. matscikit_cosmotim-0.2.2/src/MatSciKit_COSMOTIM/visualization/inset_style.py +99 -0
  39. matscikit_cosmotim-0.2.2/src/MatSciKit_COSMOTIM/visualization/journal_style.py +106 -0
  40. matscikit_cosmotim-0.2.2/src/MatSciKit_COSMOTIM/visualization/thermal_conductivity.py +252 -0
  41. matscikit_cosmotim-0.2.2/src/MatSciKit_COSMOTIM.egg-info/PKG-INFO +299 -0
  42. matscikit_cosmotim-0.2.2/src/MatSciKit_COSMOTIM.egg-info/SOURCES.txt +46 -0
  43. matscikit_cosmotim-0.2.2/src/MatSciKit_COSMOTIM.egg-info/dependency_links.txt +1 -0
  44. matscikit_cosmotim-0.2.2/src/MatSciKit_COSMOTIM.egg-info/entry_points.txt +2 -0
  45. matscikit_cosmotim-0.2.2/src/MatSciKit_COSMOTIM.egg-info/requires.txt +15 -0
  46. matscikit_cosmotim-0.2.2/src/MatSciKit_COSMOTIM.egg-info/top_level.txt +1 -0
  47. matscikit_cosmotim-0.2.2/tests/test_cif_reader.py +252 -0
  48. 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
+ [![Python 3.8+](https://img.shields.io/badge/python-3.8+-blue.svg)](https://www.python.org/downloads/)
44
+ [![License](https://img.shields.io/badge/license-MIT-green.svg)](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
+ [![Python 3.8+](https://img.shields.io/badge/python-3.8+-blue.svg)](https://www.python.org/downloads/)
6
+ [![License](https://img.shields.io/badge/license-MIT-green.svg)](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"
@@ -0,0 +1,4 @@
1
+ [egg_info]
2
+ tag_build =
3
+ tag_date = 0
4
+