diff --git a/README.md b/README.md index 00ef66d..b7f60fa 100644 --- a/README.md +++ b/README.md @@ -31,47 +31,7 @@ OptimalBranchingCore.jl -->| |--> OptimalBranching.jl ``` where `OptimalBranching.jl` is only a package interface. -## Example - -This package currently provides an implementation of the branching algorithm for the Maximum Independent Set (MIS) problem, an example is shown below: -```julia -julia> using OptimalBranching, Graphs - -# define a problem, for MIS the problem is just a graph -julia> g = random_regular_graph(20, 3) -{20, 30} undirected simple Int64 graph - -julia> problem = MISProblem(g) -MISProblem(20) - -# select the branching strategy -julia> branching_strategy = OptBranchingStrategy(TensorNetworkSolver(), IPSolver(), EnvFilter(), MinBoundarySelector(2), D3Measure()) -OptBranchingStrategy{TensorNetworkSolver, IPSolver, EnvFilter, MinBoundarySelector, D3Measure}(TensorNetworkSolver(), IPSolver(10), EnvFilter(), MinBoundarySelector(2), D3Measure()) - -julia> config = SolverConfig(MISReducer(), branching_strategy, MISSize) -SolverConfig{MISReducer, OptBranchingStrategy{TensorNetworkSolver, IPSolver, EnvFilter, MinBoundarySelector, D3Measure}, MISSize}(MISReducer(), OptBranchingStrategy{TensorNetworkSolver, IPSolver, EnvFilter, MinBoundarySelector, D3Measure}(TensorNetworkSolver(), IPSolver(10), EnvFilter(), MinBoundarySelector(2), D3Measure()), MISSize) - -# the result shows that the size of the maximum independent set is 9 -julia> branch(problem, config) -MISSize(9) - -# we can also use the EliminateGraphs package to verify the result -julia> using OptimalBranchingMIS.EliminateGraphs - -julia> mis2(EliminateGraph(g)) -9 -``` - -Furthermore, one can check the count of branches in the following way: -```julia -julia> config = SolverConfig(MISReducer(), branching_strategy, MISCount) -SolverConfig{MISReducer, OptBranchingStrategy{TensorNetworkSolver, IPSolver, EnvFilter, MinBoundarySelector, D3Measure}, MISCount}(MISReducer(), OptBranchingStrategy{TensorNetworkSolver, IPSolver, EnvFilter, MinBoundarySelector, D3Measure}(TensorNetworkSolver(), IPSolver(10), EnvFilter(), MinBoundarySelector(2), D3Measure()), MISCount) - -julia> branch(problem, config) -MISCount(9, 1) -``` -which shows that it takes only one branch to find the maximum independent set of size 9. - +For more details, please refer to the [documentation](https://ArrogantGao.github.io/OptimalBranching.jl/dev/). ## How to Contribute diff --git a/docs/make.jl b/docs/make.jl index 739845c..f4258e4 100644 --- a/docs/make.jl +++ b/docs/make.jl @@ -14,6 +14,10 @@ makedocs(; ), pages=[ "Home" => "index.md", + "Manual" => Any[ + "man/core.md", + "man/mis.md", + ], ], ) diff --git a/docs/src/index.md b/docs/src/index.md index c050c46..436f076 100644 --- a/docs/src/index.md +++ b/docs/src/index.md @@ -2,13 +2,96 @@ CurrentModule = OptimalBranching ``` -# OptimalBranching +# OptimalBranching.jl Documentation for [OptimalBranching](https://github.com/ArrogantGao/OptimalBranching.jl). -```@index +`OptimalBranching.jl` is a Julia package for automatic generation of optimal branching rule for the branch-and-bound algorithm. +This package only supply an interface for the core algorithm, and the actual implementation of the core algorithm is in `OptimalBranchingCore.jl` and `OptimalBranchingMIS.jl`, which can be found in the `lib` directory of this repository. + +## Installation + +This package has not been registered yet, so you need to add this repository manually. + +```bash +$ git clone https://github.com/ArrogantGao/OptimalBranching.jl +$ cd OptimalBranching.jl +$ make ``` -```@autodocs -Modules = [OptimalBranching] +This will add the submodules `OptimalBranchingCore.jl` and `OptimalBranchingMIS.jl` and install the dependencies, the tests will be run automatically to ensure everything is fine. + +## Dependencies + +The relation between the submodules and the package is shown in the following diagram: +``` + |-- OptimalBranchingSAT.jl --| +OptimalBranchingCore.jl -->| |--> OptimalBranching.jl + |-- OptimalBranchingMIS.jl --| ``` +where `OptimalBranching.jl` is only a package interface. + +## Example + +This package currently provides an implementation of the branching algorithm for the Maximum Independent Set (MIS) problem, an example is shown below: +```julia +julia> using OptimalBranching, Graphs + +# define a problem, for MIS the problem is just a graph +julia> g = random_regular_graph(20, 3) +{20, 30} undirected simple Int64 graph + +julia> problem = MISProblem(g) +MISProblem(20) + +# select the branching strategy +julia> branching_strategy = OptBranchingStrategy(TensorNetworkSolver(), IPSolver(), EnvFilter(), MinBoundarySelector(2), D3Measure()) +OptBranchingStrategy + ├── table_solver - TensorNetworkSolver() + ├── set_cover_solver - IPSolver(10) + ├── pruner - EnvFilter() + ├── selector - MinBoundarySelector(2) + └── measure - D3Measure() + + +julia> config = SolverConfig(MISReducer(), branching_strategy, MISSize) +SolverConfig +├── reducer - MISReducer() +├── result_type - MISSize +└── branching_strategy - OptBranchingStrategy + ├── table_solver - TensorNetworkSolver() + ├── set_cover_solver - IPSolver(10) + ├── pruner - EnvFilter() + ├── selector - MinBoundarySelector(2) + └── measure - D3Measure() + + +# the result shows that the size of the maximum independent set is 9 +julia> branch(problem, config) +MISSize(9) + +# we can also use the EliminateGraphs package to verify the result +julia> using OptimalBranchingMIS.EliminateGraphs + +julia> mis2(EliminateGraph(g)) +9 +``` + +Furthermore, one can check the count of branches in the following way: +```julia +julia> config = SolverConfig(MISReducer(), branching_strategy, MISCount) +SolverConfig{MISReducer, OptBranchingStrategy{TensorNetworkSolver, IPSolver, EnvFilter, MinBoundarySelector, D3Measure}, MISCount}(MISReducer(), OptBranchingStrategy{TensorNetworkSolver, IPSolver, EnvFilter, MinBoundarySelector, D3Measure}(TensorNetworkSolver(), IPSolver(10), EnvFilter(), MinBoundarySelector(2), D3Measure()), MISCount) + +julia> branch(problem, config) +MISCount(9, 1) +``` +which shows that it takes only one branch to find the maximum independent set of size 9. + + +## How to Contribute + +If you find any bug or have any suggestion, please open an [issue](https://github.com/ArrogantGao/OptimalBranching.jl/issues). + +## License + +This project is licensed under the MIT License. diff --git a/docs/src/man/core.md b/docs/src/man/core.md new file mode 100644 index 0000000..c187052 --- /dev/null +++ b/docs/src/man/core.md @@ -0,0 +1,18 @@ +```@meta +CurrentModule = OptimalBranchingCore +``` + +# OptimalBranchingCore + +Documentation for the core module `OptimalBranchingCore.jl`, which provides the core functionality for the optimal branching algorithm. + +## API + +```@index +Pages = ["core.md"] +``` + +```@autodocs +Modules = [OptimalBranchingCore] +Order = [:macro, :function, :type, :module] +``` \ No newline at end of file diff --git a/docs/src/man/mis.md b/docs/src/man/mis.md new file mode 100644 index 0000000..4e05716 --- /dev/null +++ b/docs/src/man/mis.md @@ -0,0 +1,19 @@ +```@meta +CurrentModule = OptimalBranchingMIS +``` + +# OptimalBranchingMIS + +Documentation for the MIS module `OptimalBranchingMIS.jl`, which provides the maximum independent set solver based on the optimal branching algorithm. + + +## API + +```@index +Pages = ["mis.md"] +``` + +```@autodocs +Modules = [OptimalBranchingMIS] +Order = [:macro, :function, :type, :module] +``` \ No newline at end of file diff --git a/lib/OptimalBranchingCore/src/types.jl b/lib/OptimalBranchingCore/src/types.jl index 490a48c..ae8c997 100644 --- a/lib/OptimalBranchingCore/src/types.jl +++ b/lib/OptimalBranchingCore/src/types.jl @@ -322,6 +322,15 @@ struct OptBranchingStrategy{TS<:AbstractTableSolver, SCS<:AbstractSetCoverSolver selector::SL measure::M end +Base.show(io::IO, strategy::OptBranchingStrategy) = print(io, +""" +OptBranchingStrategy + ├── table_solver - $(strategy.table_solver) + ├── set_cover_solver - $(strategy.set_cover_solver) + ├── pruner - $(strategy.pruner) + ├── selector - $(strategy.selector) + └── measure - $(strategy.measure) +""") """ SolverConfig @@ -339,3 +348,10 @@ struct SolverConfig{R<:AbstractReducer, B<:AbstractBranchingStrategy, TR<:Abstra branching_strategy::B result_type::Type{TR} end +Base.show(io::IO, config::SolverConfig) = print(io, +""" +SolverConfig +├── reducer - $(config.reducer) +├── result_type - $(config.result_type) +└── branching_strategy - $(config.branching_strategy) +""") \ No newline at end of file