Skip to content

Commit

Permalink
update readme
Browse files Browse the repository at this point in the history
  • Loading branch information
hdavid16 committed Apr 1, 2022
1 parent f7422df commit 589c94a
Showing 1 changed file with 12 additions and 3 deletions.
15 changes: 12 additions & 3 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -12,9 +12,12 @@ Pkg.add("DisjunctiveProgramming")

After defining a JuMP model, disjunctions can be added to the model by specifying which of the original JuMP model constraints should be assigned to each disjunction. The constraints that are assigned to the disjunctions will no longer be general model constraints, but will belong to the disjunction that they are assigned to. These constraints must be either `GreaterThan`, `LessThan`, or `EqualTo` constraints. Constraints that are of `Interval` type are currently not supported. It is assumed that the disjuncts belonging to a disjunction are proper disjunctions (mutually exclussive) and only one of them will be selected.

When a disjunction is defined using the `@disjunction` macro, the disjunctions are reformulated to algebraic constraints via the Big-M method (`reformulation = :BMR`) or the Convex Hull (`reformulation = :CHR`) as described [here](https://optimization.mccormick.northwestern.edu/index.php/Disjunctive_inequalities). For the Convex Hull Reformulation on a nonlinear model, the perspective function proposed in [Furman, et al. [2020]](https://link.springer.com/article/10.1007/s10589-020-00176-0) is used.
When a disjunction is defined using the `@disjunction` macro, the disjunctions are reformulated to algebraic constraints via either,
- The Big-M method (when `reformulation = :BMR` in the `@disjunction` macro)
- The Convex-Hull (when `reformulation = :CHR` in the `@disjunction` macro)
These approaches are described [here](https://optimization.mccormick.northwestern.edu/index.php/Disjunctive_inequalities). For the Convex-Hull reformulation, disaggregated variables are generated by adding the suffix `_$name$i` to the original variables, where `i` is the index of the disjunct in that disjunction. Bounding constraints are applied to the disaggregated variables and can be accessed with `model[Symbol("$<original var>_$name$i_lb")]` and `model[Symbol("$<original var>_$name$i_ub")]` for the lower bound and upper bound constraints, respectively. The aggregation constraint can be accessed with `model[Symbol("$<original var>_aggregation")]` When the Convex-Hull reformulation is applied to a nonlinear model, the perspective function proposed in [Furman, et al. [2020]](https://link.springer.com/article/10.1007/s10589-020-00176-0) is used.

When calling the `@disjunction` macro, a `name::Symbol` keyword argument can be specified to define the name of the indicator variable to be used for that disjunction. Otherwise, (`name = missing`) a symbolic name will be generated with the prefix `disj`.
When calling the `@disjunction` macro, a `name::Symbol` keyword argument can be specified to define the name of the binary indicator variable to be used for that disjunction. Otherwise, (`name = missing`) a symbolic name will be generated with the prefix `disj`. The mutual exclussion constraint on the binary indicator variables can be accessed with `model[Symbol("XOR($name)")]`.

For Big-M reformulations, the user may provide an `M` object that represents the BigM value(s). The `M` object can be a `Number` that is applied to all constraints in the disjuncts, or a `Vector`/`Tuple` of values that are used for each of the disjuncts. For Convex-Hull reformulations, the user may provide an `ϵ` value for the perspective function (default is `ϵ = 1e-6`). The `ϵ` object can be a `Number` that is applied to all perspective functions, or a `Vector`/`Tuple` of values that are used for each of the disjuncts.

Expand All @@ -24,7 +27,13 @@ NOTE: `:gdp_variable_refs` and `:gdp_variable_names` are forbidden JuMP model ob

## Logical Propositions

Boolean logic can be included in the model by using the `@proposition` macro. This macro will take an expression that uses only binary variables from the model (typically a subset of the indicator variables used in the disjunctions) and one or more of the following Boolean operators: `` (or, typed with `\vee + tab`), `` (and, typed with `\wedge + tab`), `¬` (negation, typed with `\neg + tab`), `` (implication, typed with `\Rightarrow + tab`), `` (double implication or equivalence, typed with `\Leftrightarrow + tab`).
Boolean logic can be included in the model by using the `@proposition` macro. This macro will take an expression that uses only binary variables from the model (typically a subset of the indicator variables used in the disjunctions) and one or more of the following Boolean operators:
- `` (or, typed with `\vee + tab`)
- `` (and, typed with `\wedge + tab`)
- `¬` (negation, typed with `\neg + tab`)
- `` (implication, typed with `\Rightarrow + tab`)
- `` (double implication or equivalence, typed with `\Leftrightarrow + tab`)
The logical proposition is then internally reformulated to an algebraic constraint that is added to the model. This constrait can be accessed with `model[Symbol("<logical proposition expression>")]`.

## Example

Expand Down

2 comments on commit 589c94a

@hdavid16
Copy link
Owner Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@JuliaRegistrator
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Registration pull request created: JuliaRegistries/General/58123

After the above pull request is merged, it is recommended that a tag is created on this repository for the registered package version.

This will be done automatically if the Julia TagBot GitHub Action is installed, or can be done manually through the github interface, or via:

git tag -a v0.1.5 -m "<description of version>" 589c94a2d422eca58595d86e67e7b4feb091417c
git push origin v0.1.5

Please sign in to comment.