Metadata-Version: 2.4
Name: vcti-derived
Version: 4.0.0
Summary: An extensible, catalog-driven library for computing derived fields from multi-component engineering data arrays
Author: Visual Collaboration Technologies Inc.
License-Expression: LicenseRef-Proprietary
Project-URL: Repository, https://github.com/vcollab/vcti-python-derived
Project-URL: Changelog, https://github.com/vcollab/vcti-python-derived/blob/main/CHANGELOG.md
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Requires-Python: <3.15,>=3.12
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=2.3
Provides-Extra: fieldset
Requires-Dist: vcti-fieldset<5,>=4.0; extra == "fieldset"
Provides-Extra: test
Requires-Dist: pytest; extra == "test"
Requires-Dist: pytest-cov; extra == "test"
Requires-Dist: vcti-fieldset<5,>=4.0; extra == "test"
Provides-Extra: lint
Requires-Dist: ruff; extra == "lint"
Provides-Extra: typecheck
Requires-Dist: mypy; extra == "typecheck"
Dynamic: license-file

# Derived Fields

An extensible, catalog-driven library for computing derived fields from multi-component engineering data arrays

## Overview

`vcti.derived` turns multi-component engineering results — vectors, 6-DOF,
symmetric stress/strain tensors — into derived fields such as magnitude, von
Mises, principal values and directions, and traction vectors. The math is
pure numpy, and the results land in a
[FieldSet](https://pypi.org/project/vcti-fieldset/): **deriving a quantity
registers it as a named, cached column and hands back a lens to it**. That
makes a derived value a first-class field — you can filter, sort, group, or
export on it, build your own expressions over it, and the next derivation
reuses it instead of recomputing (the principal values are solved once and
feed a dozen further quantities). Three layers sit over one implementation:
**kernels** (plain arrays in, arrays out), **field lenses**
(`ScalarField`, `VectorField`, `Dof6Field`, `SymmetricTensorField`,
`ComplexField`) over a FieldSet, and a **catalog** enumerating what exists
per family with stable string and integer ids. Families are 3-D; 2-D data is
embedded as 3-D by the caller. Component order is explicit, so data from any
solver (Abaqus, Nastran, Ansys, LS-Dyna) computes correctly without
reshuffling, and the output dtype is a promise this library keeps.

## Installation

```bash
pip install vcti-derived[fieldset]
```

The core (kernels and catalog) needs only numpy. The `[fieldset]` extra adds
the field lenses, which derive into a `FieldSet`.

### In `requirements.txt`

```
vcti-derived[fieldset]>=4.0.0
```

### In `pyproject.toml` dependencies

```toml
dependencies = [
    "vcti-derived[fieldset]>=4.0.0",
]
```

---

## Quick Start

```python
import numpy as np
from vcti.fieldset import FieldSet
from vcti.derived import DataFamily, SymmetricTensorField, catalogs, symtensor

# A stress tensor, one column per component
stress = np.array([[100.0, 20.0, 5.0, 15.0, 8.0, -12.0],
                   [300.0, 50.0, 10.0, 0.0, 0.0, 0.0]], dtype=np.float32)
fs = FieldSet(**{f"stress_{c}": stress[:, i].copy()
                 for i, c in enumerate(("xx", "yy", "zz", "xy", "yz", "xz"))})

field = SymmetricTensorField(fs, prefix="stress_")

# Deriving registers a named column and returns a lens to it
field.von_mises()            # -> ScalarField; fs now has "stress_von_mises"
field.max_principal()        # solves the eigenproblem once...
field.max_shear()            # ...and this reuses the cached "stress_principals"

# A derived value is an ordinary column, so it can drive what happens next
hot = fs.rows().where("stress_von_mises > 100").select()
SymmetricTensorField(hot, prefix="stress_").max_principal()   # continue on the subset

# Kernels directly, if you just have arrays:
vm = symtensor.von_mises(stress)                              # (N,)

# The catalog: what exists, and a container-free reference (accepts a permuted order)
entry = catalogs.get("symtensor.von_mises")                   # dispatch_id 7
vm = entry.compute(stress, order=["xx", "yy", "zz", "xy", "xz", "yz"])
for e in catalogs.scalar.by_family(DataFamily.SYMTENSOR):
    print(e.id, e.dispatch_id, e.display_name)
```

---

## Dependencies

- [numpy](https://numpy.org) — the only requirement of the core (kernels and
  catalog).

### Optional

- [vcti-fieldset](https://pypi.org/project/vcti-fieldset/) — required for the
  field lenses; install via `vcti-derived[fieldset]`.

---

## Documentation

| If you want to… | Read |
|---|---|
| Understand the architecture and design decisions | [docs/design.md](docs/design.md) |
| Navigate and understand the source | [docs/source-guide.md](docs/source-guide.md) |
| See practical, real-world usage | [docs/patterns.md](docs/patterns.md) |
| Extend the library | [docs/extending.md](docs/extending.md) |
