decode-mcd 1.0.0rc0

MCD generates counterfactuals that meet multiple, customizable objectives in both the feature and performance spaces.

Multiobjective-Counterfactuals-for-Design

MCD is a framework to identify tractable "counterfactual" modifications to a design that achieve a set of desired properties. MCD searches for these counterfactuals by iteratively querying a set of property predictors provided by the user. MCD is capable of recommending design modifications that meet multiple, customizable objectives in both the feature and performance spaces.

About The Project

Multiobjective Counterfactuals for Design (MCD) is a framework primarily intended for the generation of design alternatives that meet user-specified performance criteria while remaining within a certain region of the design space. To use MCD, you need a dataset of designs that are reasonably representative of the desired region of the design space, including performance metrics, as well as a model capable of predicting the performance metrics of a given design. MCD is model agnostic - this means that the model need not be a differentiable machine learning model, or, in fact, a machine learning model in the first place. MCD also offers high flexibility in terms of the number and 'type' of performance targets that can be specified. Performance targets can be any combination of:

• 'Continuous Targets': (e.g. I want suggested bike designs to weigh between 2 and 4 kilograms)
• 'Classification Targets': (e.g. I want suggested bike designs to be classified as dirt bikes)
• 'Probability Targets': (e.g. I want each suggested design to have a higher probability of belonging to classes A or B than of belonging to C or D)

Built With

• 
• 
• 
• 

Quick-Start Guide

Installation

1. Install MCD with: pip install decode-mcd
2. Run:

import random

from pymoo.core.variable import Real

import numpy as np
from decode_mcd import DesignTargets, DataPackage, MultiObjectiveProblem, CounterfactualsGenerator, ContinuousTarget

x = np.random.random(100)
x = x.reshape(100, 1)
y = x * 100


def predict(_x):
    return _x * 100 + random.random()


data_package = DataPackage(x=x,
                           y=y,
                           x_datatypes=[Real(bounds=(0, 1))])

problem = MultiObjectiveProblem(data_package=data_package,
                                prediction_function=lambda design: predict(design),
                                x_query=x[0].reshape(1, 1),
                                y_targets=DesignTargets([ContinuousTarget(label=0,
                                                                          lower_bound=25,
                                                                          upper_bound=75)]),
                                constraint_functions=[])

generator = CounterfactualsGenerator(problem=problem,
                                     pop_size=10,
                                     initialize_from_dataset=False)

generator.generate(n_generations=10)
counterfactuals = generator.sample_with_dtai(num_samples=10, gower_weight=1,
                                             avg_gower_weight=1, cfc_weight=1,
                                             diversity_weight=50)
print(counterfactuals)

Roadmap

• We are currently working on support for gradient-based optimization

See the open issues for a full list of proposed features (and known issues).

Contributing

Contributions are what make the open source community such an amazing place to learn, inspire, and create. Any contributions you make are greatly appreciated.

If you have a suggestion that would make this better, please fork the repo and create a pull request. You can also simply open an issue with the tag "enhancement". Don't forget to give the project a star! Thanks again!

1. Fork the Project
2. Create your Feature Branch (git checkout -b feature/AmazingFeature)
3. Commit your Changes (git commit -m 'Add some AmazingFeature')
4. Push to the Branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

License

Distributed under the MIT License. See LICENSE for more information.

Citation

If you use MCD for research, please consider citing our paper:

Regenwetter, L., Abu Obaideh, Y., and Ahmed, F. (July 16, 2024). "MCD: A Model-Agnostic Counterfactual Search Method For Multi-modal Design Modifications." ASME. J. Mech. Des. doi: https://doi.org/10.1115/1.4065998