carnopy 0.1.0a1__tar.gz

carnopy-0.1.0a1/.gitignore

@@ -0,0 +1,34 @@
+# Python bytecode/cache
+__pycache__/
+*.py[cod]
+
+# Test/lint/type-check caches
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+
+# Project virtual environments (uv uses .venv)
+.venv/
+venv/
+
+# uv.lock is intentionally tracked.
+
+# Build/package artifacts
+build/
+dist/
+prerelease/
+*.egg-info/
+
+# Generated datasets
+outputs/*
+!outputs/.gitkeep
+
+# Generated figures
+figures/
+
+# Local environment files
+.env
+.env.*
+
+# Operator-specific coding-agent instructions
+.agents/local.md

carnopy-0.1.0a1/AGENTS.md

@@ -0,0 +1,523 @@
+# Carnopy contributor and coding-agent guide
+
+## Authority and local instructions
+
+This file applies to the repository root and all subdirectories unless a more
+specific nested `AGENTS.md` exists.
+
+Before inspecting, testing, or changing the repository, check this exact
+repository-relative path:
+
+```text
+<repository-root>/.agents/local.md
+```
+
+If that file exists, read it in full before taking any other action. It is the
+highest-priority repository instruction for local paths, environment selection,
+allowed commands, Git authority, dependency operations, credentials, and
+publication boundaries. Do not infer permission from this public file when the
+local file is more restrictive.
+
+The tracked `AGENTS.md` remains authoritative for public scientific behavior,
+schemas, compatibility contracts, architecture, and contribution standards.
+Local instructions may narrow operational authority but must not silently alter
+those public contracts.
+
+Canonical names:
+
+```text
+Project: Carnopy
+Repository: carnopy
+Distribution: carnopy
+Import package: carnopy
+CLI: carnopy
+```
+
+CoolProp is the first backend dependency, not the project identity.
+
+Before starting an implementation stage, establish whether unrelated or
+uncommitted work is present. If the tree is dirty, pause before editing,
+describe the intended stage boundary, and suggest a Conventional Commit message
+so separate stages are not mixed accidentally. Preserve unrelated changes.
+
+Read-only Git commands are allowed when needed to inspect repository state or
+review changes. Examples include:
+
+```text
+git status --short
+git diff
+git diff --check
+git log
+git show
+git ls-files
+```
+
+Do not run Git commands that change repository state. Staging, committing,
+amending, branching, tagging, rebasing, resetting, restoring, merging, pushing,
+and changing remotes remain human-owned unless a local instruction explicitly
+grants narrower authority.
+
+Do not publish packages, create credentials, configure repository security, or
+change dependency declarations without explicit maintainer authorization.
+
+## Purpose and scope
+
+Carnopy generates reproducible, backend-derived synthetic thermophysical
+datasets for machine-learning, surrogate-model, and engineering workflows.
+
+Carnopy is not:
+
+- a thermodynamic property model;
+- experimental data or backend-independent ground truth;
+- a process simulator;
+- a machine-learning training framework.
+
+The core workflow is:
+
+```text
+sampling specification
+→ backend calls
+→ validation and stable diagnostics
+→ stable tabular schema
+→ CSV/Parquet
+→ metadata and report
+→ optional visualization of emitted columns
+```
+
+Milestone 1 supports:
+
+- CoolProp only;
+- pure fluids only;
+- YAML schema version 1;
+- `property_table`;
+- `saturation_table`;
+- `vapor_mass_fraction_table`;
+- deterministic sampling;
+- selectable CSV and/or Parquet dataset output;
+- metadata and report JSON;
+- optional Matplotlib property curves, sampled heatmaps, x-y plots, and p-v/T-s
+  diagrams;
+- configured post-generation visualization.
+
+Out of scope:
+
+- mixtures;
+- ORC generation;
+- additional property backends;
+- random, Sobol, Latin-hypercube, adaptive, or active-learning sampling;
+- ML training or inference;
+- GUI, web/API services, or databases;
+- ThermoML, OCR, RAG, or literature mining.
+
+Do not broaden scope without maintainer approval.
+
+## Development workflow
+
+Use the project-local environment and locked uv workflow described by local
+instructions. `pyproject.toml` and `uv.lock` are authoritative; do not recreate
+requirements files.
+
+Normal synchronization:
+
+```bash
+uv sync --locked --extra all --group dev
+```
+
+Release tooling:
+
+```bash
+uv sync --locked --extra all --group dev --group release
+```
+
+Required quality gate:
+
+```bash
+uv lock --check
+uv run --locked ruff check .
+uv run --locked ruff format --check .
+uv run --locked mypy src/carnopy
+uv run --locked pytest
+uv run --locked python scripts/preflight.py
+uv pip check --python .venv/bin/python
+```
+
+If a required command or dependency is unavailable, preserve the exact failure
+and ask before installing, upgrading, or substituting anything.
+
+Use:
+
+- `rg` for searches;
+- `apply_patch` for repository file edits;
+- temporary directories for generated test artifacts;
+- focused tests for every behavior change.
+
+Avoid:
+
+- monolithic modules;
+- speculative frameworks;
+- heavy imports and side effects at module import time;
+- brittle golden thermodynamic datasets;
+- pixel-perfect figure tests.
+
+Test count is not a target. Prefer a focused regression for each distinct
+contract or failure mode, use parametrization where cases share behavior, and
+remove redundant tests. The suite can still contain many tests because
+configuration, scientific modes, provenance, visualization, CLI behavior,
+packaging, and release tooling are separate public contracts.
+
+Root and subcommand help must not import CoolProp, NumPy, pandas, PyArrow, or
+Matplotlib.
+
+## Public interfaces
+
+The public CLI is:
+
+```text
+carnopy --version
+carnopy init MODE OUTPUT [--create-parents]
+carnopy properties
+carnopy fluids
+carnopy validate CONFIG.yaml
+carnopy generate CONFIG.yaml [--out PATH] [--figures-out PATH]
+carnopy inspect SOURCE
+carnopy plot SOURCE ...
+```
+
+The documented workflow is:
+
+```text
+init → edit → optional validate → generate → inspect → optional plot
+```
+
+Commands remain independently scriptable; do not add implicit chaining.
+
+The supported Python API intentionally remains narrow:
+
+- `load_config`;
+- `validate_config`;
+- `generate_dataset`;
+- public configuration and result models;
+- explicit visualization functions.
+
+Keep CLI handlers thin and scientific logic outside `cli.py`.
+
+## Configuration and sampling contracts
+
+Every configuration contains:
+
+```yaml
+schema_version: 1
+backend: coolprop
+mode: property_table
+fluids: [...]
+grid: ...
+properties: [...]
+```
+
+Optional `outputs:` and `visualization:` sections are allowed. Dataset format
+selection affects artifact-generation context but not scientific `spec_id`.
+Visualization must not affect scientific or artifact-generation identity.
+
+Dataset formats:
+
+```yaml
+outputs:
+  dataset_formats: [csv, parquet]
+```
+
+Omission defaults to both formats. At least one of `csv` or `parquet` is
+required. Canonical format order is CSV then Parquet.
+
+Public samplers:
+
+```text
+explicit
+linspace
+stepspace
+geomspace
+logspace
+```
+
+`stepspace` is inclusive and requires a reachable endpoint. Public `arange` is
+not supported.
+
+Supported input units:
+
+```text
+temperature: K, degC
+pressure: Pa, kPa, MPa, bar
+vapor_mass_fraction: "1"
+```
+
+All backend calls and generated numeric columns use SI. Preserve original
+units and sampler declarations in metadata.
+
+The row limit is 1,000,000 after sampler materialization, fluid
+canonicalization, Cartesian expansion, and saturation endpoint expansion.
+
+Mode contracts:
+
+- `property_table` requires temperature and pressure;
+- `saturation_table` requires exactly one of temperature or pressure and emits
+  separate liquid and vapor endpoint rows;
+- `vapor_mass_fraction_table` requires vapor mass fraction plus exactly one of
+  temperature or pressure.
+
+Public `vapor_mass_fraction` maps to CoolProp `Q` only inside the adapter.
+Use \(x_{\mathrm{vap}}\) as its scientific symbol in figures and equations;
+do not rename the public schema or dataset field.
+
+## Scientific behavior
+
+Use the official CoolProp documentation as the backend authority:
+
+- https://coolprop.org/coolprop/
+- https://coolprop.org/coolprop/HighLevelAPI.html
+- https://github.com/CoolProp/CoolProp
+
+Reset every requested canonical fluid to CoolProp `DEF` once after validation
+and before row evaluation. Do not change reference state during generation.
+
+Specific enthalpy, entropy, and internal energy are reference-state dependent.
+Absolute values are not directly comparable across different reference
+conventions.
+
+If actual CoolProp behavior contradicts an approved contract:
+
+1. Stop before implementing a workaround.
+2. Preserve fluid, normalized inputs, property, mode, CoolProp version,
+   exception type/message, and observed result.
+3. Explain the contradiction.
+4. Ask the maintainer to decide.
+
+Do not silently change input pairs, phase rules, numerical methods, schemas, or
+backend behavior.
+
+## Rows, validity, and failures
+
+Every row includes:
+
+```text
+run_id
+case_id
+mode
+fluid
+backend
+backend_version
+phase
+backend_phase
+valid
+failure_layer
+failure_code
+failure_message
+failure_property
+backend_error_type
+backend_error_message
+```
+
+`case_id` is zero-based and assigned after deterministic final ordering.
+
+Milestone 1 uses strict row validity. Any required coordinate, phase, or
+requested-property failure invalidates the row. Successfully evaluated values
+may remain populated; failed values remain null.
+
+Do not infer stable failure categories by brittle parsing of backend messages.
+Preserve raw backend diagnostics separately.
+
+## Provenance and immutable artifacts
+
+Identity meanings:
+
+- `spec_id`: canonical executable scientific specification;
+- `generation_context_id`: artifact-generation context;
+- `output_request_id`: canonical CSV/Parquet serialization request;
+- `run_id`: one UUID4 generation attempt;
+- artifact hashes: exact emitted bytes;
+- `visualization_request_id`: normalized visualization request.
+
+Generation writes immutable run directories containing:
+
+```text
+dataset.csv
+dataset.parquet
+config.original.yaml
+config.normalized.json
+metadata.json
+report.json
+```
+
+Human-facing names use:
+
+```text
+<UTC-second>_<mode-slug>_<eight-character-run-prefix>
+```
+
+The directory name is a locator, not dataset identity.
+
+Runs are staged and atomically renamed. Never overwrite an existing final or
+staging directory. Do not add host source-config paths to metadata.
+
+Tests use temporary directories. Do not commit generated datasets or figures.
+
+## Visualization contracts
+
+Visualization is a reproducible view of emitted columns:
+
+- never call a thermodynamic backend;
+- never smooth, interpolate, extrapolate, or invent states;
+- preserve invalid and missing gaps;
+- derive only `specific_volume = 1 / mass_density`;
+- use semantic scientific labels and units;
+- keep visualization identity separate from dataset identity.
+
+Supported kinds:
+
+```text
+property_curves
+property_heatmap
+xy
+pv
+ts
+```
+
+CLI spelling uses `property-curves` and `property-heatmap`.
+
+Manual exports:
+
+- prefer Parquet in run directories;
+- fall back to CSV for CSV-only runs;
+- verify recorded source hashes;
+- write outside immutable source runs;
+- write an image plus `.plot.json`;
+- refuse existing image or sidecar paths;
+- finalize using exclusive same-filesystem hard links;
+- remain no-overwrite-safe but not fully two-file crash-atomic.
+
+Configured visualization:
+
+- validates before thermodynamic generation;
+- executes after dataset finalization;
+- writes under a separate figure root;
+- records one `visualization-report.json`;
+- preserves successful figures after another plot fails;
+- never changes `config.normalized.json`, `spec_id`,
+  `generation_context_id`, or dataset artifact hashes.
+
+`carnopy inspect SOURCE` reports emitted plotting capabilities without backend
+calls. `carnopy plot RUN --config FILE.yaml` batch-renders a top-level
+`visualization:` section against an existing immutable run. Batch rendering
+must ignore scientific fields in a full generation config and validate only
+against emitted run columns.
+
+Dataset `run_status` remains solely about row validity.
+
+## Architecture
+
+The high-level pipeline is:
+
+```text
+YAML
+  → validated configuration
+  → canonical SI scientific specification
+  → thin backend adapter
+  → mode-specific rows
+  → stable DataFrame schema
+  → immutable CSV/Parquet + metadata/report
+  → optional emitted-column visualization
+```
+
+The backend boundary contains only capabilities needed by current modes. It is
+not a plugin framework. Add abstractions only when concrete additional backend
+requirements exist.
+
+Keep focused module boundaries:
+
+- configuration parsing and normalization;
+- semantic domain registries;
+- backend adapter;
+- mode generators;
+- output/provenance writers;
+- visualization requests, selection, rendering, and automation.
+
+## Packaging and release safeguards
+
+Use the `src/` layout and Hatchling:
+
+```toml
+[build-system]
+requires = ["hatchling>=1.27.0"]
+build-backend = "hatchling.build"
+```
+
+Matplotlib remains optional through `viz`; `all` must remain synchronized with
+all user-facing extras. PyArrow remains core.
+
+The first intended public release is `0.1.0a1`. The release workflow builds one
+wheel and sdist, verifies them, requires human approval, and publishes them to
+production PyPI through GitHub OIDC Trusted Publishing.
+
+Only a human maintainer may:
+
+- make the repository public;
+- configure GitHub environments or Trusted Publishers;
+- create or push release tags;
+- approve production deployment;
+- publish to PyPI.
+
+Never rebuild changed payloads under an uploaded version. Any changed payload
+requires a new version. Never use `skip-existing` to repair a partial release.
+
+Distribution checks:
+
+```bash
+uv run --locked --group release python -m build
+uv run --locked --group release python -m twine check dist/*
+uv run --locked python scripts/check_distribution.py dist/*
+```
+
+`python -m build` normally uses its default isolated build environment. That
+environment installs the `[build-system]` requirements declared in
+`pyproject.toml`. Do not modify the development environment solely to satisfy
+the build backend. Use the ignored, repository-local `prerelease/` directory
+for non-destructive rehearsal builds when an existing `dist/` must be
+preserved. Final release artifacts belong in `dist/`. Do not write Carnopy
+build artifacts outside the repository.
+
+## Commit messages
+
+Use:
+
+```text
+<type>(<scope>): <imperative summary>
+```
+
+Rules:
+
+- lowercase type and scope;
+- imperative mood: `add`, `fix`, `validate`, `reject`, `document`;
+- concise summary, ideally no more than 72 characters;
+- no trailing period;
+- body only when the reason or tradeoff matters.
+
+Common types:
+
+```text
+feat fix test docs refactor chore ci build perf style
+```
+
+Recommended scopes:
+
+```text
+dataset schema sampler coolprop cli validation metadata tests docs ci
+packaging viz
+```
+
+Examples:
+
+```text
+feat(viz): add configured visualization outputs
+fix(validation): reject duplicate canonical fluids
+test(sampler): cover descending stepspace ranges
+docs(project): consolidate public guidance
+build(packaging): declare parquet runtime dependency
+```

carnopy-0.1.0a1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Göran Cem Alpay
+
+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.