# ParetoFlow
ParetoFlow is a Python package for offline multi-objective optimization using Generative Flow Models with Multi Predictors Guidance to approximate the Pareto front.
## Installation
```bash
conda create -n paretoflow python=3.10
conda activate paretoflow
pip install paretoflow
```
## Usage
We accept `.py` files for input features and labels, where the continuous features has shape `(n_samples, n_dim)`, and the discrete features has shape `(n_samples, seq_len)`.
The labels are the objective values, with shape `(n_samples, n_obj)`.
When having discrete features, we need to convert the discrete features to continuous logits, as stated in the [ParetoFlow paper](https://arxiv.org/abs/2412.03718). The implementation follows the [design-bench](https://github.com/brandontrabucco/design-bench).
In our implementation, we support both z-score normalization and min-max normalization.
In our paper, we use z-score normalization for training the proxies and flow matching model. Min-max normalization is used for calculating the hypervolume, aligining with [offline-moo](https://github.com/lamda-bbo/offline-moo?tab=readme-ov-file#offline-multi-objective-optimization).
If you have your data as `x.npy` and `y.npy`, you can use the following code to train the proxies and flow matching model (continuous features for illustration, see the `examples/discrete_examples.py` for discrete features):
```python
import numpy as np
from paretoflow import ParetoFlow
# Load the data
all_x = np.load("examples/data/zdt1-x-0.npy")
all_y = np.load("examples/data/zdt1-y-0.npy")
# If need to train the flow matching and proxies models
# Initialize the ParetoFlow sampler
pf = ParetoFlow(
task_name="zdt1",
input_x=all_x,
input_y=all_y,
x_lower_bound=np.array([0.0] * all_x.shape[1]),
x_upper_bound=np.array([1.0] * all_x.shape[1]),
)
# Sample the Pareto Set
res_x, res_y = pf.sample()
print(len(res_x))
```
Or you can load the pre-trained flow matching and proxies models:
```python
import numpy as np
import torch
from paretoflow import ParetoFlow, VectorFieldNet, FlowMatching, MultipleModels
# If load pre-trained flow matching and proxies models
# Initialize the ParetoFlow sampler
vnet = VectorFieldNet(all_x.shape[1])
fm_model = FlowMatching(vnet=vnet, sigma=0.0, D=all_x.shape[1], T=1000)
fm_model = torch.load("saved_fm_models/zdt1.model")
# Create the proxies model and load the saved model
proxies_model = MultipleModels(
n_dim=all_x.shape[1],
n_obj=all_y.shape[1],
train_mode="Vanilla",
hidden_size=[2048, 2048],
save_dir="saved_proxies/",
save_prefix="MultipleModels-Vanilla-zdt1",
)
proxies_model.load()
pf = ParetoFlow(
task_name="zdt1",
input_x=all_x,
input_y=all_y,
x_lower_bound=np.array([0.0] * all_x.shape[1]),
x_upper_bound=np.array([1.0] * all_x.shape[1]),
load_pretrained_fm=True,
load_pretrained_proxies=True,
fm_model=fm_model,
proxies=proxies_model,
)
res_x, res_y = pf.sample()
print(len(res_x))
```
**More Importantly**, we also allow users to pass in their own pretrained flow matching and proxies models. We require the flow matching model to be a `nn.Module` object and also pass in two key arguments `vnet` and `time_embedding`, which are both `nn.Module` objects. The `vnet` is the network approximation for the vector field in the flow matching model, and the `time_embedding` is a mapping from continuous time between [0, 1] to the embedding space. See more details in the docstrings of the `ParetoFlow` class.
# Citation
If you find ParetoFlow useful in your research, please consider citing:
```bibtex
@misc{yuan2024paretoflowguidedflowsmultiobjective,
title={ParetoFlow: Guided Flows in Multi-Objective Optimization},
author={Ye Yuan and Can Chen and Christopher Pal and Xue Liu},
year={2024},
eprint={2412.03718},
archivePrefix={arXiv},
primaryClass={cs.CE},
url={https://arxiv.org/abs/2412.03718},
}
```
Raw data
{
"_id": null,
"home_page": "https://github.com/StevenYuan666/ParetoFlow",
"name": "paretoflow",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": null,
"keywords": "optimization",
"author": "Ye Yuan, Can Chen",
"author_email": "ye.yuan3@mail.mcgill.ca",
"download_url": "https://files.pythonhosted.org/packages/42/a8/5085997d303cfd14c04eaafd65548500c9f38e9cc33632cd7bf2658c35ec/paretoflow-0.1.4.tar.gz",
"platform": "any",
"description": "# ParetoFlow\nParetoFlow is a Python package for offline multi-objective optimization using Generative Flow Models with Multi Predictors Guidance to approximate the Pareto front.\n\n## Installation\n\n```bash\nconda create -n paretoflow python=3.10\nconda activate paretoflow\npip install paretoflow\n```\n\n## Usage\nWe accept `.py` files for input features and labels, where the continuous features has shape `(n_samples, n_dim)`, and the discrete features has shape `(n_samples, seq_len)`.\nThe labels are the objective values, with shape `(n_samples, n_obj)`.\n\nWhen having discrete features, we need to convert the discrete features to continuous logits, as stated in the [ParetoFlow paper](https://arxiv.org/abs/2412.03718). The implementation follows the [design-bench](https://github.com/brandontrabucco/design-bench).\n\nIn our implementation, we support both z-score normalization and min-max normalization.\nIn our paper, we use z-score normalization for training the proxies and flow matching model. Min-max normalization is used for calculating the hypervolume, aligining with [offline-moo](https://github.com/lamda-bbo/offline-moo?tab=readme-ov-file#offline-multi-objective-optimization).\n\nIf you have your data as `x.npy` and `y.npy`, you can use the following code to train the proxies and flow matching model (continuous features for illustration, see the `examples/discrete_examples.py` for discrete features):\n```python\nimport numpy as np\nfrom paretoflow import ParetoFlow\n\n# Load the data\nall_x = np.load(\"examples/data/zdt1-x-0.npy\")\nall_y = np.load(\"examples/data/zdt1-y-0.npy\")\n\n# If need to train the flow matching and proxies models\n# Initialize the ParetoFlow sampler\npf = ParetoFlow(\n task_name=\"zdt1\",\n input_x=all_x,\n input_y=all_y,\n x_lower_bound=np.array([0.0] * all_x.shape[1]),\n x_upper_bound=np.array([1.0] * all_x.shape[1]),\n)\n\n# Sample the Pareto Set\nres_x, res_y = pf.sample()\n\nprint(len(res_x))\n```\n\nOr you can load the pre-trained flow matching and proxies models:\n```python\nimport numpy as np\nimport torch\nfrom paretoflow import ParetoFlow, VectorFieldNet, FlowMatching, MultipleModels\n\n# If load pre-trained flow matching and proxies models\n# Initialize the ParetoFlow sampler\nvnet = VectorFieldNet(all_x.shape[1])\nfm_model = FlowMatching(vnet=vnet, sigma=0.0, D=all_x.shape[1], T=1000)\nfm_model = torch.load(\"saved_fm_models/zdt1.model\")\n\n# Create the proxies model and load the saved model\nproxies_model = MultipleModels(\n n_dim=all_x.shape[1],\n n_obj=all_y.shape[1],\n train_mode=\"Vanilla\",\n hidden_size=[2048, 2048],\n save_dir=\"saved_proxies/\",\n save_prefix=\"MultipleModels-Vanilla-zdt1\",\n)\nproxies_model.load()\n\npf = ParetoFlow(\n task_name=\"zdt1\",\n input_x=all_x,\n input_y=all_y,\n x_lower_bound=np.array([0.0] * all_x.shape[1]),\n x_upper_bound=np.array([1.0] * all_x.shape[1]),\n load_pretrained_fm=True,\n load_pretrained_proxies=True,\n fm_model=fm_model,\n proxies=proxies_model,\n)\n\nres_x, res_y = pf.sample()\n\nprint(len(res_x))\n```\n\n**More Importantly**, we also allow users to pass in their own pretrained flow matching and proxies models. We require the flow matching model to be a `nn.Module` object and also pass in two key arguments `vnet` and `time_embedding`, which are both `nn.Module` objects. The `vnet` is the network approximation for the vector field in the flow matching model, and the `time_embedding` is a mapping from continuous time between [0, 1] to the embedding space. See more details in the docstrings of the `ParetoFlow` class.\n\n# Citation\n\nIf you find ParetoFlow useful in your research, please consider citing:\n\n```bibtex\n@misc{yuan2024paretoflowguidedflowsmultiobjective,\n title={ParetoFlow: Guided Flows in Multi-Objective Optimization}, \n author={Ye Yuan and Can Chen and Christopher Pal and Xue Liu},\n year={2024},\n eprint={2412.03718},\n archivePrefix={arXiv},\n primaryClass={cs.CE},\n url={https://arxiv.org/abs/2412.03718}, \n}\n```\n",
"bugtrack_url": null,
"license": "MIT License",
"summary": "Paretoflow is a Python package for offline multi-objective optimization using Generative Flow Models with Multi Predictors Guidance to approximate the Pareto front.",
"version": "0.1.4",
"project_urls": {
"Homepage": "https://github.com/StevenYuan666/ParetoFlow"
},
"split_keywords": [
"optimization"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "42a85085997d303cfd14c04eaafd65548500c9f38e9cc33632cd7bf2658c35ec",
"md5": "29ba477b55d76796669d8f56e7bcdee9",
"sha256": "d05726b906e3c9d8c9e2380c9b3189a29a05efa8eb3874fe59957b58950e11de"
},
"downloads": -1,
"filename": "paretoflow-0.1.4.tar.gz",
"has_sig": false,
"md5_digest": "29ba477b55d76796669d8f56e7bcdee9",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 25936,
"upload_time": "2024-12-29T03:34:10",
"upload_time_iso_8601": "2024-12-29T03:34:10.317601Z",
"url": "https://files.pythonhosted.org/packages/42/a8/5085997d303cfd14c04eaafd65548500c9f38e9cc33632cd7bf2658c35ec/paretoflow-0.1.4.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-12-29 03:34:10",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "StevenYuan666",
"github_project": "ParetoFlow",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [
{
"name": "numpy",
"specs": [
[
"==",
"1.23.2"
]
]
},
{
"name": "scipy",
"specs": [
[
"==",
"1.10.1"
]
]
},
{
"name": "setuptools",
"specs": [
[
"==",
"75.1.0"
]
]
}
],
"lcname": "paretoflow"
}
JSON
