update docs

OptimalBranching · Nov 24, 2024 · 64a56ca · 64a56ca
1 parent 740cba8
commit 64a56ca
Show file tree

Hide file tree

Showing 6 changed files with 145 additions and 45 deletions.
diff --git 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
@@ -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
@@ -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
@@ -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]
+```
diff --git a/docs/src/man/mis.md 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]
+```
diff --git 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) 
+""")