# Property-Driven Machine Learning
A general framework for property-driven machine learning that enables incorporating logical properties and constraints into neural network training and evaluation.
## Features
- **Multiple Logic Systems**: Support for Boolean logic, fuzzy logics (Gödel, Łukasiewicz, Reichenbach, Yager, etc.), Signal Temporal Logic (STL), and DL2
- **Property Constraints**: Built-in constraint classes for robustness properties, Lipschitz constraints, output bounds, and group fairness
- **Adversarial Training**: PGD and Auto-PGD attack implementations for constraint evaluation
- **Gradient Normalization**: GradNorm for balancing multiple training objectives
## Installation
### From PyPI (Recommended)
```bash
# Install the latest version from PyPI
pip install property-driven-ml
# Or install with uv (faster)
uv add property-driven-ml
```
### From Source (Development)
For development or to run the latest features:
#### Prerequisites
This project uses [uv](https://docs.astral.sh/uv/) for fast Python package and project management. Install uv first:
```bash
# On macOS and Linux
curl -LsSf https://astral.sh/uv/install.sh | sh
# On Windows
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"
# Or with pip
pip install uv
```
#### Installation Steps
```bash
# Clone the repository
git clone https://github.com/tflinkow/property-driven-ml.git
cd property-driven-ml
# Install dependencies and the package (recommended)
uv sync
# Or install in development mode with pip
pip install -e .
# Or install directly
pip install .
```
### Requirements
- Python 3.11+
- PyTorch 2.5.1+
- CUDA support (optional, for GPU acceleration)
**Note**:
- For PyPI installation: Use standard `python` commands
- For local development with uv: Use `uv run python` to run scripts with the managed environment
## Quick Start
### Using the Command Line Interface
After installation from PyPI:
```bash
# Get help on available options
property-driven-ml --help
# Run a training experiment
property-driven-ml \
--data-set=mnist \
--batch-size=64 \
--lr=0.001 \
--epochs=10 \
--input-region="EpsilonBall(eps=0.1)" \
--output-constraint="StandardRobustness(delta=0.05)" \
--experiment-name="mnist_robustness" \
--logic=GD
```
For local development:
```bash
# Run from the repository root
uv run python main.py --help
```
### Basic API Usage
```python
import torch
import property_driven_ml.logics as logics
import property_driven_ml.constraints as constraints
import property_driven_ml.training as training
# Create a logic system
logic = logics.GoedelFuzzyLogic()
# Define a robustness constraint
device = torch.device('cuda' if torch.cuda.is_available() else 'cpu')
constraint = constraints.StandardRobustnessConstraint(device, delta=0.1)
# Set up adversarial attack for constraint evaluation
x_sample = torch.randn(1, 3, 32, 32).to(device) # Example input
oracle = training.PGD(x_sample, logic, device, steps=20, restarts=10, step_size=0.01)
# Use in training loop
model = torch.nn.Sequential(
torch.nn.Flatten(),
torch.nn.Linear(3072, 128),
torch.nn.ReLU(),
torch.nn.Linear(128, 10)
).to(device)
# Evaluate constraint satisfaction
x = torch.randn(8, 3, 32, 32).to(device)
x_adv = oracle.attack(model, x, None, x.min(), x.max(), constraint)
loss, satisfaction = constraint.eval(model, x, x_adv, None, logic)
```
### Available Logic Systems
```python
import property_driven_ml.logics as logics
# Access logic systems through the logics module
logic_boolean = logics.BooleanLogic() # Classical Boolean logic
logic_godel = logics.GoedelFuzzyLogic() # Gödel fuzzy logic
logic_lukasiewicz = logics.LukasiewiczFuzzyLogic() # Łukasiewicz fuzzy logic
logic_reichenbach = logics.ReichenbachFuzzyLogic() # Reichenbach fuzzy logic
logic_yager = logics.YagerFuzzyLogic() # Yager fuzzy logic
logic_stl = logics.STL() # Signal Temporal Logic
logic_dl2 = logics.DL2() # DL2 logic
```
### Available Constraints
```python
import property_driven_ml.constraints as constraints
# Access constraint classes through the constraints module
robustness = constraints.StandardRobustnessConstraint(device, delta=0.1) # Adversarial robustness
lipschitz = constraints.LipschitzRobustnessConstraint(device, L=1.0) # Lipschitz continuity
output_bounds = constraints.AlsomitraOutputConstraint(device, lo, hi) # Output bounds
group_fair = constraints.GroupConstraint(device, groups, delta=0.1) # Group fairness
input_region = constraints.EpsilonBall(dataset, eps=0.1, mean, std) # Input perturbation regions
```
## Architecture
The framework is organized into several key modules:
- `property_driven_ml.logics`: Logic systems for constraint evaluation
- `property_driven_ml.constraints`: Property constraint definitions
- `property_driven_ml.training`: Training utilities (attacks, gradient normalization)
- `property_driven_ml.util`: Utility functions
## Examples
### Command-Line Usage
If you installed from PyPI, use the CLI directly:
```bash
# Run a complete training experiment
property-driven-ml \
--data-set=mnist \
--batch-size=64 \
--lr=0.001 \
--epochs=10 \
--input-region="EpsilonBall(eps=0.1)" \
--output-constraint="StandardRobustness(delta=0.05)" \
--experiment-name="mnist_robustness" \
--logic=GD
```
For local development:
```bash
# Run from the root directory with uv
uv run python main.py \
--data-set=mnist \
--batch-size=64 \
--lr=0.001 \
--epochs=10 \
--input-region="EpsilonBall(eps=0.1)" \
--output-constraint="StandardRobustness(delta=0.05)" \
--experiment-name="mnist_robustness" \
--logic=GD
# Or run the shell script with multiple experiments
cd examples && bash run.sh
```
### Programmatic Usage
Write your own scripts using the framework:
```python
import property_driven_ml.logics as logics
import property_driven_ml.constraints as constraints
# Your custom training code here...
```
For local development examples:
```bash
# Simple API demonstration
uv run python examples/simple_example.py
```
### Available Examples (Local Development)
- `main.py`: Full training pipeline with command-line interface (root level)
- `examples/simple_example.py`: Clean API demonstration
- `examples/models.py`: Neural network architectures for different tasks
- `examples/alsomitra_dataset.py`: Custom dataset implementation
- `examples/run.sh`: Batch training experiments
## Contributing
Contributions are welcome! Please feel free to submit pull requests or open issues for bugs and feature requests.
### Development Setup
This project uses uv for dependency management and development workflows:
```bash
# Clone and set up the development environment
git clone https://github.com/tflinkow/property-driven-ml.git
cd property-driven-ml
# Install all dependencies (including dev dependencies)
uv sync
# Run tests
uv run pytest
# Run examples and scripts
uv run python main.py --help
uv run python examples/simple_example.py
# Add new dependencies
uv add torch torchvision # Runtime dependency
uv add --dev pytest mypy # Development dependency
```
## License
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
## Citation
If you use this framework in your research, please cite:
```bibtex
@article{flinkow2025general,
title={A General Framework for Property-Driven Machine Learning},
author={Flinkow, Thomas and Casadio, Marco and Kessler, Colin and Monahan, Rosemary and Komendantskaya, Ekaterina},
journal={arXiv preprint arXiv:2505.00466},
year={2025},
url={https://arxiv.org/abs/2505.00466}
}
```
You can also cite the software implementation:
```bibtex
@software{property_driven_ml,
title={Property-Driven Machine Learning Framework},
author={Thomas Flinkow},
year={2025},
url={https://github.com/tflinkow/property-driven-ml}
}
```
Raw data
{
"_id": null,
"home_page": null,
"name": "property-driven-ml",
"maintainer": "Thomas Flinkow, Gusts Gustavs Grinbergs",
"docs_url": null,
"requires_python": ">=3.11",
"maintainer_email": null,
"keywords": "machine learning, property driven, constraints, fuzzy logic, adversarial training, neural networks, pytorch",
"author": "Thomas Flinkow, Gusts Gustavs Grinbergs",
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/0d/c5/3c4edb7877184d1b22229a4fd31037955a05e12db6bdc9c1e2b9d3a4c9e0/property_driven_ml-0.1.1.tar.gz",
"platform": null,
"description": "# Property-Driven Machine Learning\n\nA general framework for property-driven machine learning that enables incorporating logical properties and constraints into neural network training and evaluation.\n\n## Features\n\n- **Multiple Logic Systems**: Support for Boolean logic, fuzzy logics (G\u00f6del, \u0141ukasiewicz, Reichenbach, Yager, etc.), Signal Temporal Logic (STL), and DL2\n- **Property Constraints**: Built-in constraint classes for robustness properties, Lipschitz constraints, output bounds, and group fairness\n- **Adversarial Training**: PGD and Auto-PGD attack implementations for constraint evaluation\n- **Gradient Normalization**: GradNorm for balancing multiple training objectives\n\n## Installation\n\n### From PyPI (Recommended)\n\n```bash\n# Install the latest version from PyPI\npip install property-driven-ml\n\n# Or install with uv (faster)\nuv add property-driven-ml\n```\n\n### From Source (Development)\n\nFor development or to run the latest features:\n\n#### Prerequisites\n\nThis project uses [uv](https://docs.astral.sh/uv/) for fast Python package and project management. Install uv first:\n\n```bash\n# On macOS and Linux\ncurl -LsSf https://astral.sh/uv/install.sh | sh\n\n# On Windows\npowershell -c \"irm https://astral.sh/uv/install.ps1 | iex\"\n\n# Or with pip\npip install uv\n```\n\n#### Installation Steps\n\n```bash\n# Clone the repository\ngit clone https://github.com/tflinkow/property-driven-ml.git\ncd property-driven-ml\n\n# Install dependencies and the package (recommended)\nuv sync\n\n# Or install in development mode with pip\npip install -e .\n\n# Or install directly\npip install .\n```\n\n### Requirements\n\n- Python 3.11+\n- PyTorch 2.5.1+\n- CUDA support (optional, for GPU acceleration)\n\n**Note**: \n- For PyPI installation: Use standard `python` commands\n- For local development with uv: Use `uv run python` to run scripts with the managed environment\n\n## Quick Start\n\n### Using the Command Line Interface\n\nAfter installation from PyPI:\n```bash\n# Get help on available options\nproperty-driven-ml --help\n\n# Run a training experiment\nproperty-driven-ml \\\n --data-set=mnist \\\n --batch-size=64 \\\n --lr=0.001 \\\n --epochs=10 \\\n --input-region=\"EpsilonBall(eps=0.1)\" \\\n --output-constraint=\"StandardRobustness(delta=0.05)\" \\\n --experiment-name=\"mnist_robustness\" \\\n --logic=GD\n```\n\nFor local development:\n```bash\n# Run from the repository root\nuv run python main.py --help\n```\n\n### Basic API Usage\n\n```python\nimport torch\nimport property_driven_ml.logics as logics\nimport property_driven_ml.constraints as constraints\nimport property_driven_ml.training as training\n\n# Create a logic system\nlogic = logics.GoedelFuzzyLogic()\n\n# Define a robustness constraint\ndevice = torch.device('cuda' if torch.cuda.is_available() else 'cpu')\nconstraint = constraints.StandardRobustnessConstraint(device, delta=0.1)\n\n# Set up adversarial attack for constraint evaluation\nx_sample = torch.randn(1, 3, 32, 32).to(device) # Example input\noracle = training.PGD(x_sample, logic, device, steps=20, restarts=10, step_size=0.01)\n\n# Use in training loop\nmodel = torch.nn.Sequential(\n torch.nn.Flatten(),\n torch.nn.Linear(3072, 128),\n torch.nn.ReLU(),\n torch.nn.Linear(128, 10)\n).to(device)\n\n# Evaluate constraint satisfaction\nx = torch.randn(8, 3, 32, 32).to(device)\nx_adv = oracle.attack(model, x, None, x.min(), x.max(), constraint)\nloss, satisfaction = constraint.eval(model, x, x_adv, None, logic)\n```\n\n### Available Logic Systems\n\n```python\nimport property_driven_ml.logics as logics\n\n# Access logic systems through the logics module\nlogic_boolean = logics.BooleanLogic() # Classical Boolean logic\nlogic_godel = logics.GoedelFuzzyLogic() # G\u00f6del fuzzy logic\nlogic_lukasiewicz = logics.LukasiewiczFuzzyLogic() # \u0141ukasiewicz fuzzy logic\nlogic_reichenbach = logics.ReichenbachFuzzyLogic() # Reichenbach fuzzy logic\nlogic_yager = logics.YagerFuzzyLogic() # Yager fuzzy logic\nlogic_stl = logics.STL() # Signal Temporal Logic\nlogic_dl2 = logics.DL2() # DL2 logic\n```\n\n### Available Constraints\n\n```python\nimport property_driven_ml.constraints as constraints\n\n# Access constraint classes through the constraints module\nrobustness = constraints.StandardRobustnessConstraint(device, delta=0.1) # Adversarial robustness\nlipschitz = constraints.LipschitzRobustnessConstraint(device, L=1.0) # Lipschitz continuity\noutput_bounds = constraints.AlsomitraOutputConstraint(device, lo, hi) # Output bounds\ngroup_fair = constraints.GroupConstraint(device, groups, delta=0.1) # Group fairness\ninput_region = constraints.EpsilonBall(dataset, eps=0.1, mean, std) # Input perturbation regions\n```\n\n## Architecture\n\nThe framework is organized into several key modules:\n\n- `property_driven_ml.logics`: Logic systems for constraint evaluation\n- `property_driven_ml.constraints`: Property constraint definitions\n- `property_driven_ml.training`: Training utilities (attacks, gradient normalization)\n- `property_driven_ml.util`: Utility functions\n\n## Examples\n\n### Command-Line Usage\n\nIf you installed from PyPI, use the CLI directly:\n```bash\n# Run a complete training experiment\nproperty-driven-ml \\\n --data-set=mnist \\\n --batch-size=64 \\\n --lr=0.001 \\\n --epochs=10 \\\n --input-region=\"EpsilonBall(eps=0.1)\" \\\n --output-constraint=\"StandardRobustness(delta=0.05)\" \\\n --experiment-name=\"mnist_robustness\" \\\n --logic=GD\n```\n\nFor local development:\n```bash\n# Run from the root directory with uv\nuv run python main.py \\\n --data-set=mnist \\\n --batch-size=64 \\\n --lr=0.001 \\\n --epochs=10 \\\n --input-region=\"EpsilonBall(eps=0.1)\" \\\n --output-constraint=\"StandardRobustness(delta=0.05)\" \\\n --experiment-name=\"mnist_robustness\" \\\n --logic=GD\n\n# Or run the shell script with multiple experiments\ncd examples && bash run.sh\n```\n\n### Programmatic Usage\n\nWrite your own scripts using the framework:\n```python\nimport property_driven_ml.logics as logics\nimport property_driven_ml.constraints as constraints\n\n# Your custom training code here...\n```\n\nFor local development examples:\n```bash\n# Simple API demonstration\nuv run python examples/simple_example.py\n```\n\n### Available Examples (Local Development)\n- `main.py`: Full training pipeline with command-line interface (root level)\n- `examples/simple_example.py`: Clean API demonstration\n- `examples/models.py`: Neural network architectures for different tasks\n- `examples/alsomitra_dataset.py`: Custom dataset implementation\n- `examples/run.sh`: Batch training experiments\n\n## Contributing\n\nContributions are welcome! Please feel free to submit pull requests or open issues for bugs and feature requests.\n\n### Development Setup\n\nThis project uses uv for dependency management and development workflows:\n\n```bash\n# Clone and set up the development environment\ngit clone https://github.com/tflinkow/property-driven-ml.git\ncd property-driven-ml\n\n# Install all dependencies (including dev dependencies)\nuv sync\n\n# Run tests\nuv run pytest\n\n# Run examples and scripts\nuv run python main.py --help\nuv run python examples/simple_example.py\n\n# Add new dependencies\nuv add torch torchvision # Runtime dependency\nuv add --dev pytest mypy # Development dependency\n```\n\n## License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n## Citation\n\nIf you use this framework in your research, please cite:\n\n```bibtex\n@article{flinkow2025general,\n title={A General Framework for Property-Driven Machine Learning},\n author={Flinkow, Thomas and Casadio, Marco and Kessler, Colin and Monahan, Rosemary and Komendantskaya, Ekaterina},\n journal={arXiv preprint arXiv:2505.00466},\n year={2025},\n url={https://arxiv.org/abs/2505.00466}\n}\n```\n\nYou can also cite the software implementation:\n\n```bibtex\n@software{property_driven_ml,\n title={Property-Driven Machine Learning Framework},\n author={Thomas Flinkow},\n year={2025},\n url={https://github.com/tflinkow/property-driven-ml}\n}\n```\n",
"bugtrack_url": null,
"license": null,
"summary": "A general framework for property-driven machine learning with logical constraints",
"version": "0.1.1",
"project_urls": {
"Bug Tracker": "https://github.com/ggustavs/property-driven-ml/issues",
"Documentation": "https://github.com/ggustavs/property-driven-ml#readme",
"Homepage": "https://github.com/ggustavs/property-driven-ml",
"Repository": "https://github.com/ggustavs/property-driven-ml"
},
"split_keywords": [
"machine learning",
" property driven",
" constraints",
" fuzzy logic",
" adversarial training",
" neural networks",
" pytorch"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "03340f6b95a34ae66413873d37cb901027d2290fdee52f9b52d212ed06153296",
"md5": "4085b514cc9b667e9d9905fe46607b62",
"sha256": "4d953ed64010c021f5f780dbf5733db849fe8bf804ed78009c2d05874a0c7a31"
},
"downloads": -1,
"filename": "property_driven_ml-0.1.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "4085b514cc9b667e9d9905fe46607b62",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.11",
"size": 17493,
"upload_time": "2025-08-18T15:34:37",
"upload_time_iso_8601": "2025-08-18T15:34:37.782008Z",
"url": "https://files.pythonhosted.org/packages/03/34/0f6b95a34ae66413873d37cb901027d2290fdee52f9b52d212ed06153296/property_driven_ml-0.1.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "0dc53c4edb7877184d1b22229a4fd31037955a05e12db6bdc9c1e2b9d3a4c9e0",
"md5": "f71588fcfe6507891451f9cd71995e30",
"sha256": "c39909f1a349cc7f80ac652243f0317d1591edefa296020e99570cfb0bb84689"
},
"downloads": -1,
"filename": "property_driven_ml-0.1.1.tar.gz",
"has_sig": false,
"md5_digest": "f71588fcfe6507891451f9cd71995e30",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.11",
"size": 16661,
"upload_time": "2025-08-18T15:34:39",
"upload_time_iso_8601": "2025-08-18T15:34:39.424439Z",
"url": "https://files.pythonhosted.org/packages/0d/c5/3c4edb7877184d1b22229a4fd31037955a05e12db6bdc9c1e2b9d3a4c9e0/property_driven_ml-0.1.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-18 15:34:39",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "ggustavs",
"github_project": "property-driven-ml",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"requirements": [
{
"name": "idx2numpy",
"specs": [
[
"==",
"1.2.3"
]
]
},
{
"name": "numpy",
"specs": [
[
"==",
"1.26.3"
]
]
},
{
"name": "onnx",
"specs": [
[
"==",
"1.17.0"
]
]
},
{
"name": "onnxruntime",
"specs": [
[
"==",
"1.20.1"
]
]
},
{
"name": "pandas",
"specs": [
[
"==",
"2.2.3"
]
]
},
{
"name": "torch",
"specs": [
[
"==",
"2.2.0+cu121"
]
]
},
{
"name": "torchvision",
"specs": [
[
"==",
"0.17.0+cu121"
]
]
}
],
"lcname": "property-driven-ml"
}
JSON
