Bare minimum documentation

README.md

@@ -1,7 +1,72 @@
-# PowerModelsDistributionRDT.jl
+# PowerModelsDistributionRDT
 
-**BETA / IN ACTIVE DEVELOPMENT: Features will change quickly and without warning**
+|                                      **Documentation**                                       |                                          **Build Status**                                          |
+| :------------------------------------------------------------------------------------------: | :------------------------------------------------------------------------------------------------: |
+| [![docs-stable][docs-stable-img]][docs-stable-url] [![docs-dev][docs-dev-img]][docs-dev-url] | [![github-actions][github-actions-img]][github-actions-url] [![codecov][codecov-img]][codecov-url] |
+
+This package combines various packages in the [InfrastructureModels.jl](https://github.com/lanl-ansi/InfrastructureModels.jl) optimization library ecosystem, particularly those related to electric power distribution.
+
+PowerModelsDistributionRDT focuses on optimal design of phase unbalanced (multiconductor) distribution feeders, primarily for meeting resilience metrics. Phase unbalanced modeling is achieved using [PowerModelsDistribution](https://github.com/lanl-ansi/PowerModelsDistribution.jl). This library features a custom implementation of network design for resilience. See [documentation][docs-stable-url] for more details.
+
+## Installation
+
+To install PowerModelsDistributionRDT, use the built-in Julia package manager
+
+```julia
+pkg> add PowerModelsDistributionRDT
+```
+
+Or, equivalently, via the `Pkg` API:
+
+```julia
+julia> import Pkg; Pkg.add("PowerModelsDistributionRDT")
+```
+
+or to develop the package,
+
+```julia
+julia> import Pkg; Pkg.develop(Pkg.PackageSpec(; name="PowerModelsDistributionRDT", url="https://github.com/lanl-ansi/PowerModelsDistributionRDT.jl"))
+```
+
+## Questions and contributions
+
+Usage questions can be posted on the [Github Discussions forum][discussions-url].
+
+Contributions, feature requests, and suggestions are welcome; please open an [issue][issues-url] if you encounter any problems. The [contributing page][contrib-url] has guidelines that should be followed when opening pull requests and contributing code.
+
+This software was supported by the LPNORM project funded by the U.S. Department of Energy's Microgrid Research and Development Program.
+
+## Citing PowerModelsDistributionRDT
+
+If you find PowerModelsDistributionRDT useful for your work, we kindly request that you cite the following [publication](https://doi.org/10.1287/ijoc.2019.0899):
+
+```bibtex
+@article{byeon2020communication,
+  title={Communication-constrained expansion planning for resilient distribution systems},
+  author={Byeon, Geunyeong and Van Hentenryck, Pascal and Bent, Russell and Nagarajan, Harsha},
+  journal={INFORMS Journal on Computing},
+  volume={32},
+  number={4},
+  pages={968--985},
+  year={2020},
+  publisher={INFORMS}
+}
+```
+
+which first introduced the problem specification implemented in this software.
 
 ## License
 
-This code is provided under a BSD license as part of the Multi-Infrastructure Control and Optimization Toolkit (MICOT) project, LA-CC-13-108.
+This code is provided under a BSD license as part of the Multi-Infrastructure Control and Optimization Toolkit (MICOT) project, C15024.
+
+[docs-dev-img]: https://github.com/lanl-ansi/PowerModelsDistributionRDT.jl/workflows/Documentation/badge.svg
+[docs-dev-url]: https://lanl-ansi.github.io/PowerModelsDistributionRDT.jl/dev
+[docs-stable-img]: https://github.com/lanl-ansi/PowerModelsDistributionRDT.jl/workflows/Documentation/badge.svg
+[docs-stable-url]: https://lanl-ansi.github.io/PowerModelsDistributionRDT.jl/stable
+[github-actions-img]: https://github.com/lanl-ansi/PowerModelsDistributionRDT.jl/workflows/CI/badge.svg
+[github-actions-url]: https://github.com/lanl-ansi/PowerModelsDistributionRDT.jl/actions/workflows/ci.yml
+[codecov-img]: https://codecov.io/gh/lanl-ansi/PowerModelsDistributionRDT.jl/branch/main/graph/badge.svg
+[codecov-url]: https://codecov.io/gh/lanl-ansi/PowerModelsDistributionRDT.jl
+[contrib-url]: https://lanl-ansi.github.io/PowerModelsDistributionRDT.jl/stable/developer/contributing.html
+[discussions-url]: https://github.com/lanl-ansi/PowerModelsDistributionRDT.jl/discussions
+[issues-url]: https://github.com/lanl-ansi/PowerModelsDistributionRDT.jl/issues

docs/Project.toml

@@ -1,5 +1,13 @@
 [deps]
+Conda = "8f4d0f93-b110-5947-807f-2305c1781a2d"
 Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
+Gumbo = "708ec375-b3d6-5a57-a7ce-8257bf98657a"
+Pluto = "c3e4b0f8-55cb-11ea-2926-15256bba5781"
+PyCall = "438e738f-606a-5dbb-bf0a-cddfbfd45ab0"
 
 [compat]
+Conda = "1.8"
 Documenter = "1"
+Gumbo = "0.8"
+Pluto = "0.19"
+PyCall = "1.95"

docs/make.jl

@@ -2,6 +2,42 @@ using Documenter
 using PowerModelsDistributionRDT
 
 
+pages = [
+    "Introduction" => "index.md",
+    "installation.md",
+    "Manual" => [
+        "Getting Started" => "manual/quickguide.md",
+#        "The RDT Workflow" => "manual/rdt_workflow.md",
+#        "Resilient Design Mathematical Model" => "manual/rdt_model.md",
+    ],
+    "Tutorials" => [
+#        "Beginners Guide" => "tutorials/Beginners Guide.md",
+#        "RDT Basic Example" => "tutorials/Block MLD Basic Example.md",
+#        "JuMP Model by Hand - RDT Example" => "tutorials/JuMP Model by Hand - MLD-Block.md",
+#        "Use Case Examples" => "tutorials/Use Case Examples.md",
+    ],
+#    "API Reference" => [
+#        "Base functions" => "reference/base.md",
+#        "Data Handling" => "reference/data.md",
+#        "GraphML Functions" => "reference/graphml.md",
+#        "Main Entrypoint" => "reference/entrypoint.md",
+#        "Internal Functions" => "reference/internal.md",
+#        "IO Functions" => "reference/io.md",
+#        "Logging" => "reference/logging.md",
+#        "Optimization Problems" => "reference/prob.md",
+#        "Solution Statistics" => "reference/stats.md",
+#        "Variables and Constraints" => "reference/variable_constraint.md",
+#        "Types" => "reference/types.md",
+#    ],
+#    "Schemas" => schema_pages,
+#    "Developer Docs" => [
+#        "Contributing Guide" => "developer/contributing.md",
+#        "Style Guide" => "developer/style.md",
+#        "Roadmap" => "developer/roadmap.md",
+#    ],
+]
+
+
 # build documents
 makedocs(
     format=Documenter.HTML(
@@ -13,6 +49,7 @@ makedocs(
     warnonly=true,
     sitename="PowerModelsDistributionRDT",
     authors="Russell Bent, Jose Tabarez, David M Fobes, and contributors",
+    pages = pages
 )
 
 # Documenter can also automatically deploy documentation to gh-pages.

docs/src/index.md

@@ -1,3 +1,46 @@
 # PowerModelsDistributionRDT.jl
 
-Documentation for PowerModelsDistributionRDT.jl
+```@meta
+CurrentModule = PowerModelsDistributionRDT
+```
+
+## What is PowerModelsDistributionRDT?
+
+[PowerModelsDistributionRDT.jl](https://github.com/lanl-ansi/PowerModelsDistributionRDT.jl) is a Julia/JuMP-based library for designing distribution networks, in particular unbalanced (i.e., multiconductor) power distribution networks.
+
+## Resources for Getting Started
+
+Read the [Installation Guide](@ref Installation-Guide)
+
+Read the [Quickstart Guide](@ref Quick-Start-Guide)
+
+Read the introductory tutorial [Introduction to PowerModelsDistributionRDT](@ref Introduction-to-PowerModelsDistributionRDT)
+
+## How the documentation is structured
+
+The following is a high-level overview of how our documentation is structured. There are three primary sections:
+
+- The **Manual** contains detailed documentation for certain aspects of PowerModelsDistributionRDT, such as
+
+- **Tutorials** contains working examples of how to use PowerModelsDistributionRDT. Start here if you are new to PowerModelsDistributionRDT.
+
+- The **API Reference** contains a complete list of the functions you can use in PowerModelsDistributionRDT. Look here if you want to know how to use a particular function.
+
+## PowerModelsDistributionRDT Analyses Packages
+
+PowerModelsDistribution depends on several other PowerModels(...) packages from the InfrastructureModels ecosystem. The packages in blue below are created and maintained by the core InfrastructureModels developer team, and the other packages are those that are built as extensions or rely on one of the core InfrastructureModels packages in some way.
+
+![InfrastructureModels Ecosystem](assets/infrastructuremodels_ecosystem.png)
+
+### PowerModelsDistribution
+
+[PowerModelsDistribution.jl](https://github.com/lanl-ansi/PowerModelsDistribution.jl) is a Julia/JuMP-based package for modeling unbalanced (i.e., multiconductor) power networks. This is the primary modeling framework utilized in PowerModelsDistributionRDT, and contains the primary logic for optimization and parsing of network data.
+
+### PowerModelsONM
+
+[PowerModelsONM.jl](https://github.com/lanl-ansi/PowerModelsONM.jl) is a Julia/JuMP-based package for operation and restoration of electric power distribution feeders featuring networked microgrids. Many of the formulations for optimal operations under extreme events are integrated into the design model of PowerModelDistributionRDT.
+
+
+## License
+
+This code is provided under a BSD license as part of the Multi-Infrastructure Control and Optimization Toolkit (MICOT) project, C15024.

docs/src/installation.md

@@ -0,0 +1,36 @@
+# Installation Guide
+
+From Julia, PowerModelsDistributionRDT is installed using the built-in package manager:
+
+```julia
+]add PowerModelsDistributionRDT
+```
+
+or equivalently,
+
+```julia
+import Pkg
+Pkg.add("PowerModelsDistributionRDT")
+```
+
+## Developer Installation
+
+To install PowerModelsDistributionRDT as a developer,
+
+```julia
+import Pkg
+Pkg.develop(Pkg.PackageSpec(; name="PowerModelsDistributionRDT", url="https://github.com/lanl-ansi/PowerModelsDistributionRDT.jl"))
+```
+
+From the command-line, outside Julia, one could download the repository, either via Github.com, or using git, _i.e._,
+
+```sh
+git clone https://github.com/lanl-ansi/PowerModelsDistributionRDT.jl.git
+git checkout tags/v1.0.0
+```
+
+Then to install PowerModelsDistributionRDT and its required packages
+
+```sh
+julia --project="path/to/PowerModelsDistributionRDT" -e 'using Pkg; Pkg.instantiate(); Pkg.precompile();'
+```

docs/src/manual/quickguide.md

@@ -0,0 +1,46 @@
+# Quick Start Guide
+
+Once PowerModelsDistributionRDT is [installed](@ref Installation-Guide), to operate PowerModelsDistributionRDT several other things are required, at a minimum, a distribution data set in LPNORM [format](https://github.com/lanl-ansi/micot/wiki/Resilient-Design-Executable) and an optimization solver like Juniper is needed.  The basic RDT problems can be executed with
+
+
+```julia
+using PowerModelsDistributionRDT
+
+import PowerModelsDistribution as _PMD
+import Ipopt
+import Juniper
+import HiGHS
+
+
+ipopt_solver = JuMP.optimizer_with_attributes(Ipopt.Optimizer, "print_level" => 0, "sb" => "yes", "max_iter" => 1000, "acceptable_tol" => 1.0e-2)
+highs_solver = JuMP.optimizer_with_attributes(HiGHS.Optimizer, "small_matrix_value" => 1e-12, "output_flag"=>false)
+juniper_solver = JuMP.optimizer_with_attributes(Juniper.Optimizer, "nl_solver" => ipopt_solver, "mip_solver" => highs_solver, "log_levels" => [],)
+
+result = solve_rdt("test/data/small.json", _PMD.ACPUPowerModel, juniper_solver)
+```
+
+where ACPUPowerModel can be replaced with a desired distribution network formulation, typically defined in the PowerModelsDistribution package.
+
+## Getting Results
+
+The solve commands in PowerModelsDistributionRDT return detailed results data in the form of a dictionary.  This dictionary can be saved for further processing as follows,
+
+```julia
+result = olve_rdt("test/data/small.json", _PMD.ACPUPowerModel, juniper_solver)
+```
+
+For example, the algorithm's runtime and final objective value can be accessed with,
+
+```
+result["solve_time"]
+result["objective"]
+```
+
+The `"solution"` field contains detailed information about the solution produced by the solve method.
+For example, the following dictionary comprehension can be used to inspect the choice to build a new branch in the solution,
+
+```
+Dict(name => data["ze"] for (name, data) in result["solution"]["branch_ne"])
+```
+
+The `print_summary(result["solution"])` function can be used show an table-like overview of the solution data.