talosdb 0.1.0__py3-none-any.whl

talosdb-0.1.0.dist-info/METADATA

@@ -0,0 +1,159 @@
+Metadata-Version: 2.4
+Name: talosdb
+Version: 0.1.0
+Summary: Lightweight experiment storage library for scientific simulations.
+Author-email: GrindelfP <grindelf.perlomutrovij@gmail.com>
+License: MIT
+Project-URL: Homepage, https://github.com/GrindelfP/talosdb
+Project-URL: Repository, https://github.com/GrindelfP/talosdb
+Project-URL: Bug Tracker, https://github.com/GrindelfP/talosdb/issues
+Keywords: experiment,simulation,storage,science,numpy
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=1.24
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: pytest-cov; extra == "dev"
+Dynamic: license-file
+
+# talosdb
+
+Lightweight experiment storage library for scientific simulations.
+Named after Talos I station.
+
+## Installation
+
+```bash
+pip install src
+```
+
+## Quickstart
+
+```python
+from src import TalosDB
+from itertools import product
+
+db = TalosDB("~/science/results")
+exp = db.experiment("vc_sweep_2025")
+
+A_grid = [0.5, 1.0, 1.5]
+beta_grid = [1.0, 2.0]
+
+for A, beta in product(A_grid, beta_grid):
+    result = simulate(A, beta)  # numpy array
+    with exp.run({"A": A, "beta": beta}) as run:
+        run.save(result)
+        run.save_params({"gamma": 0.1, "T": 300})  # extra constants
+        run.save_plot(my_plot_fn, result)
+```
+
+## File layout
+
+```
+db_root/
+└── vc_sweep_2025/
+    ├── experiment.json          # metadata: name, creation date
+    ├── A=0.5_beta=1.0/
+    │   ├── data.dat             # human-readable TSV (numpy array)
+    │   ├── params.json          # all parameters (name + extra)
+    │   └── plot.png             # if save_plot() was called
+    └── A=1.0_beta=2.0/
+        ├── data.dat
+        └── params.json
+```
+
+## API reference
+
+### TalosDB
+
+```python
+db = TalosDB("path/to/db")        # creates root folder if absent
+db.experiment("name")              # create / open experiment
+db.experiment()                    # name = datetime stamp
+db.list_experiments()              # → list[str]
+db.delete_experiment("name", confirm=True)
+```
+
+### Experiment
+
+```python
+exp = db.experiment("my_exp")
+
+# Create / open a run
+run  = exp.run({"A": 0.5, "beta": 1.0})
+# or as context manager (marks failed.json on exception):
+with exp.run({"A": 0.5, "beta": 1.0}) as run:
+    ...
+
+# Load
+run  = exp.load({"A": 0.5, "beta": 1.0})   # exact match
+runs = exp.query({"beta": 1.0})             # subset match → list[Run]
+runs = exp.all_runs()                        # every run
+```
+
+### Run
+
+```python
+run.save(result)                            # numpy array → data.dat
+run.save_params({"gamma": 0.1, "T": 300})  # extra params → params.json
+run.save_plot(plot_fn, result)              # calls plot_fn(result, path)
+
+result = run.load_data()                    # → np.ndarray
+params = run.load_params()                  # → dict
+run.is_failed()                             # → bool
+run.load_failure()                          # → dict with error info
+```
+
+### plot_fn contract
+
+```python
+def my_plot_fn(result, save_path):
+    fig, ax = plt.subplots()
+    ax.plot(result[:, 0], result[:, 1])
+    fig.savefig(save_path)
+    plt.close(fig)
+```
+
+talosdb does not import matplotlib — rendering is entirely the caller's responsibility.
+
+## .dat format
+
+Arrays are stored as human-readable TSV with a small header:
+
+```
+# shape: 100 2
+# dtype: float64
+0.0	0.001
+0.1	0.043
+...
+```
+
+3D+ arrays are split into labelled 2D slices:
+
+```
+# shape: 2 3 4
+# dtype: float64
+# slice [0]
+1.0	2.0	3.0	4.0
+5.0	6.0	7.0	8.0
+9.0	10.0	11.0	12.0
+
+# slice [1]
+...
+```
+
+The shape header ensures exact reconstruction on load regardless of dimensionality.
+
+## License
+
+MIT

talosdb-0.1.0.dist-info/RECORD

@@ -0,0 +1,5 @@
+talosdb-0.1.0.dist-info/licenses/LICENSE,sha256=-SN7FF-VT9R0IsQoNzHt0F4CLtUWRqm9gzk6Af7ZUzE,1066
+talosdb-0.1.0.dist-info/METADATA,sha256=1ZZj7Id-9H9lxD4G9OOm_5zdAM3ffZeADdu7K9-FJCc,4182
+talosdb-0.1.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+talosdb-0.1.0.dist-info/top_level.txt,sha256=AbpHGcgLb-kRsJGnwFEktk7uzpZOCcBY74-YBdrKVGs,1
+talosdb-0.1.0.dist-info/RECORD,,

talosdb-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

talosdb-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 GrindelfP
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

talosdb-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+