Metadata-Version: 2.4
Name: vdd
Version: 3.1.0
Summary: Tools for Value-Driven Design
Author-email: Alex Corrie <ajccode@gmail.com>
License: MIT
License-File: LICENSE
Requires-Python: >=3.11
Requires-Dist: numpy>=1.26
Requires-Dist: openpyxl<4,>=3.0.10
Requires-Dist: pandas>=2.0
Requires-Dist: platformdirs>=2.6.2
Requires-Dist: pygsheets<3,>=2.0.5
Requires-Dist: typer>=0.12
Requires-Dist: xlrd<3,>=2.0
Description-Content-Type: text/markdown

Tools for Value-Driven Design
=============================

<!-- badges -->

[![cc-angular][cc-angular-badge]][cc-home]
[![release-tool][release-please-badge]][release-please-gh]

<!-- / -->


Tools intended to help with modelling decisions in a value centric
design process. The intent is to keep this as generic as possible, as
some of this decision modelling is suited to generic decision-making,
non-design activities with a little massaging.


Features
-------

  - Concept Design Analysis (CODA) method implementation
  - Requirements weighting with a Binary Weighting Matrix
  - Programmatic or Spreadsheet based model creation (via Excel
    workbooks or Google Sheets).
  - Native JSON serialisation for both CODA models and Binary
    Weighting Matrices (human-readable, git-diff-friendly).
  - Command-line interface for quick model inspection and interactive weighting


Install
-------

    pip install vdd


CLI
---

`vdd` ships with a command-line interface for the two core workflows.

### Inspect a CODA model

Load a CODA model from an Excel file and print the overall design merit
alongside a per-requirement satisfaction summary:

    vdd coda path/to/model.xlsx

By default the compact Excel format is assumed. Pass `--parser full` for the
standard format:

    vdd coda path/to/model.xlsx --parser full

### Weight requirements interactively

Step through a pairwise comparison of requirements and print the resulting
normalised scores:

    vdd requirements weight "Lightweight" "Stiff" "Durable"

Questions are shuffled by default. Pass `--no-shuffle` to work through them
in a fixed order.


JSON model i/o
--------------

Both CODA models and Binary Weighting Matrices serialise to and from a
flat, human-readable JSON format. This is handy for version-controlling
models or moving them between the two tools.

```python
from vdd.coda.models import CODA
from vdd.requirements.models import BinWM

# Weight requirements with a binary weighting matrix, then persist it.
bwm = BinWM('Stiffness', 'Friction', 'Weight')
bwm.prompt()
bwm.to_json('weights.json')

# Seed a CODA model directly from the weighting matrix scores.
coda = CODA()
coda.add_requirements_from(bwm)

# Round-trip a CODA model through JSON.
coda.to_json('model.json')
reloaded = CODA.read_json('model.json')
```

`to_json()` returns a string when no path is given. `to_dict()` /
`from_dict()` expose the same data as plain-python dicts. The BinWM
format (`{"requirements": [...], "binary_matrix": [[...]]}`) is the
same shape used by the bundled example fixtures.


Documentation
-------

Currently just stored in the repo.

  - [Using Google Sheets for requirements matrices][binwm-gsheets]
  - tbc


Development
-----------

In the repository root:

	uv sync


### Releases

Managed by [Release Please][release-please-gh] with auto-versioning.
Changes to default branch will be accumulated in a release PR based on [Conventional Commits][cc-home].
Merging the release PR will automatically publish the versioned package to PyPI.


Roadmap
-------

  - Model sets for comparative work (rather than a single set of
	characteristic parameter values)
  - Improved visualisation
  - Export CODA models to Excel template
  - House of Quality style requirement/characteristic weighting
  - Pandas everywhere (v1.x)


References
----------

Based on my own degree notes and open access literature:

  - M.H. Eres et al, 2014. Mapping Customer Needs to Engineering
	Characteristics: An Aerospace Perspective for Conceptual Design -
	Journal of Engineering Design pp. 1-24
	<http://eprints.soton.ac.uk/id/eprint/361442>




<!-- links -->

[cc-angular-badge]: https://img.shields.io/badge/conventional_commits-angular-FE5196?logo=conventionalcommits&
[cc-home]: https://www.conventionalcommits.org
[release-please-badge]: https://img.shields.io/badge/release--please-python-4285F4?logo=google
[release-please-gh]: https://github.com/googleapis/release-please

[binwm-gsheets]: ./docs/gsheets-integration.md
