Rename run_* to solve_* (#807)

* rename "run" functions to "solve" functions
* add function deprecation warnings

Author: ccoffrin

CHANGELOG.md

@@ -2,6 +2,7 @@ PowerModels.jl Change Log
 =========================
 
 ### Staged
+- Rename `run_*` methods to `solve_*` and add depreciation warnings (#649)
 - Made case name recovery optional in PTI parsing
 - Fixed Julia deprecation warning when calling sort on Dict
 - Change `Int64` types to `Int`
@@ -45,6 +46,7 @@ PowerModels.jl Change Log
 - Removed ref bus index from AdmittanceMatrix (#760) (breaking)
 - Removed data change tracking from `correct_network_data!` (breaking)
 - Removed `_extend_pwl_cost!` function (#716)
+>>>>>>> master
 
 ### v0.17.4
 - Added support for matrix-based analysis of basic network data (#728)

docs/src/experiment-results.md

@@ -11,9 +11,9 @@ All models were solved using [IPOPT](https://link.springer.com/article/10.1007/s
 This experiment consists of running the following PowerModels commands,
 ```
 solver = optimizer_with_attributes(Ipopt.Optimizer, "tol" => 1e-6)
-result_ac  = run_opf(case,   ACPPowerModel, solver)
-result_soc = run_opf(case, SOCWRPowerModel, solver)
-result_qc  = run_opf(case,  QCRMPowerModel, solver)
+result_ac  = solve_opf(case,   ACPPowerModel, solver)
+result_soc = solve_opf(case, SOCWRPowerModel, solver)
+result_qc  = solve_opf(case,  QCRMPowerModel, solver)
 ```
 for each case in the PGLib-OPF archive.
 If the value of `result["termination_status"]` is `LOCALLY_SOLVED` then the

docs/src/multi-networks.md

@@ -41,7 +41,7 @@ PowerModels.ismultinetwork(pm3)
     ```
     will result in an error. Moreover, `instantiate_model()` (see )
 
-Because this is a common pattern of usage, we provide corresponding calls to `run_mn_opf` (which behaves analogously to `run_opf`, but for multinetwork data).
+Because this is a common pattern of usage, we provide corresponding calls to `solve_mn_opf` (which behaves analogously to `solve_opf`, but for multinetwork data).
 
 !!! note
 

docs/src/network-data.md

@@ -160,19 +160,19 @@ PowerModels.print_summary(network_data) # mixed units form
 Another useful helper function is `update_data`, which takes two network data dictionaries and updates the values in the first dictionary with the values from the second dictionary.  This is particularly helpful when applying sparse updates to network data.  A good example is using the solution of one computation to update the data in preparation for a second computation, like so,
 ```
 data = PowerModels.parse_file("matpower/case3.m")
-opf_result = run_ac_opf(data, Ipopt.Optimizer)
+opf_result = solve_ac_opf(data, Ipopt.Optimizer)
 PowerModels.print_summary(opf_result["solution"])
 
 PowerModels.update_data!(data, opf_result["solution"])
-pf_result = run_ac_pf(data, Ipopt.Optimizer)
+pf_result = solve_ac_pf(data, Ipopt.Optimizer)
 PowerModels.print_summary(pf_result["solution"])
 ```
 
 A variety of helper functions are available for processing the topology of the network.  For example, `connected_components` will compute the collections of buses that are connected by branches (i.e. the network's islands).  By default PowerModels will attempt to solve all of the network components simultaneously.  The `select_largest_component` function can be used to only consider the largest component in the network.  Finally the `propagate_topology_status!` can be used to explicitly deactivate components that are implicitly inactive due to the status of other components (e.g. deactivating branches based on the status of their connecting buses), like so,
 ```
 data = PowerModels.parse_file("matpower/case3.m")
 PowerModels.propagate_topology_status!(data)
-opf_result = run_ac_opf(data, Ipopt.Optimizer)
+opf_result = solve_ac_opf(data, Ipopt.Optimizer)
 ```
 The `test/data/matpower/case7_tplgy.m` case provides an example of the kind of component status deductions that can be made.  The `simplify_network!`, `propagate_topology_status!` and `deactivate_isolated_components!` functions can be helpful in diagnosing network models that do not converge or have an infeasible solution.
 

docs/src/power-flow.md

@@ -18,7 +18,7 @@ available in PowerModels and under what circumstances they may be beneficial.
 The general purpose power flow solver in PowerModels is,
 
 ```@docs
-run_pf
+solve_pf
 ```
 
 This function builds a JuMP model for a wide variety of the power flow formulations
@@ -28,15 +28,15 @@ supported by PowerModels.  For example it supports,
 * `SOCWRPowerModel` - a convex quadratic relaxation of the power flow problem
 * `DCPPowerModel` - a linear DC approximation of the power flow problem
 The typical `ACPPowerModel` and `DCPPowerModel` formulations are available via
-the shorthand form `run_ac_pf` and `run_dc_pf` respectively.
+the shorthand form `solve_ac_pf` and `solve_dc_pf` respectively.
 
-The `run_pf` solution method is both formulation and solver agnostic and
+The `solve_pf` solution method is both formulation and solver agnostic and
 can leverage the wide range of solvers that are available in the JuMP
 ecosystem.  Many of these solvers are commercial-grade, which in turn makes
-`run_pf` the most reliable power flow solution method in PowerModels.
+`solve_pf` the most reliable power flow solution method in PowerModels.
 
 !!! note
-    Use of `run_pf` is highly recommended over the other solution methods for
+    Use of `solve_pf` is highly recommended over the other solution methods for
     increased robustness.  Applications that benefit from the Julia native
     solution methods are an exception to this general rule.
 
@@ -61,7 +61,7 @@ For each bus,
 * `vi_start` - imaginary voltage starting point for the `ACRPowerModel` model
 
 The following helper function can be used to use the solution point in the
-network data as the starting point for `run_ac_pf`.
+network data as the starting point for `solve_ac_pf`.
 ```@docs
 set_ac_pf_start_values!
 ```
@@ -84,10 +84,10 @@ with voltages in polar coordinates with NLsolve.
 ```@docs
 compute_ac_pf
 ```
-`compute_ac_pf` will typically provide an identical result to `run_ac_pf`.
+`compute_ac_pf` will typically provide an identical result to `solve_ac_pf`.
 However, the existence of solution degeneracy around generator injection
 assignments and multiple power flow solutions can yield different results.
-The primary advantage of `compute_ac_pf` over `run_ac_pf` is that it does not
+The primary advantage of `compute_ac_pf` over `solve_ac_pf` is that it does not
 require building a JuMP model.  If the initial point for the AC Power Flow
 solution is near-feasible then `compute_ac_pf` can result in a significant
 runtime saving by converging quickly and reducing data-wrangling and memory
@@ -96,7 +96,7 @@ allocation overheads.  This initial guess is provided using the standard
 way of setting a suitable starting point.
 
 !!! tip
-    If `compute_ac_pf` fails to converge try `run_ac_pf` instead.
+    If `compute_ac_pf` fails to converge try `solve_ac_pf` instead.
 
 
 ## Native DC Power Flow
@@ -108,15 +108,14 @@ built-in linear systems solvers.
 ```@docs
 compute_dc_pf
 ```
-The `compute_dc_pf` method should provide identical results to `run_dc_pf`.
-The primary advantage of `compute_dc_pf` over `run_dc_pf` is that it does not
+The `compute_dc_pf` method should provide identical results to `solve_dc_pf`.
+The primary advantage of `compute_dc_pf` over `solve_dc_pf` is that it does not
 require building a JuMP model.  This results in significant memory saving and
 marginal performance saving due to reduced data-wrangling overhead.  The
 primary use-case of this model is to compute the voltage angle values from
 a collection of bus injections when working with a formulation that does not
 explicitly model these values, such as a PTDF or LODF formulation.
-The [`run_opf_ptdf_branch_power_cuts`](@ref) utility function provides an example of
-how `compute_dc_pf` is typically used.
+The [`solve_opf_ptdf_branch_power_cuts`](@ref) utility function provides an example of how `compute_dc_pf` is typically used.
 
 This solver does not support warm starting.
 
@@ -133,7 +132,7 @@ Both of these methods require a complete network data with a valid voltage solut
 for computing the branch flows.  For example, one common work flow to recover
 branch flow values is,
 ```julia
-result = run_ac_pf(network, ...)
+result = solve_ac_pf(network, ...)
 # check that the solver converged
 update_data!(network, result["solution"])
 flows = calc_branch_flow_ac(network)

docs/src/quickguide.md

@@ -6,19 +6,19 @@ Once PowerModels is installed, Ipopt is installed, and a network data file (e.g.
 using PowerModels
 using Ipopt
 
-run_ac_opf("matpower/case3.m", Ipopt.Optimizer)
+solve_ac_opf("matpower/case3.m", Ipopt.Optimizer)
 ```
 
 Similarly, a DC Optimal Power Flow can be executed with
 
 ```julia
-run_dc_opf("matpower/case3.m", Ipopt.Optimizer)
+solve_dc_opf("matpower/case3.m", Ipopt.Optimizer)
 ```
 
 PTI `.raw` files in the PSS(R)E v33 specification can be run similarly, e.g. in the case of an AC Optimal Power Flow
 
 ```julia
-run_ac_opf("case3.raw", Ipopt.Optimizer)
+solve_ac_opf("case3.raw", Ipopt.Optimizer)
 ```
 
 
@@ -27,7 +27,7 @@ run_ac_opf("case3.raw", Ipopt.Optimizer)
 The run commands in PowerModels return detailed results data in the form of a dictionary. Results dictionaries from either Matpower `.m` or PTI `.raw` files will be identical in format. This dictionary can be saved for further processing as follows,
 
 ```julia
-result = run_ac_opf("matpower/case3.m", Ipopt.Optimizer)
+result = solve_ac_opf("matpower/case3.m", Ipopt.Optimizer)
 ```
 
 For example, the algorithm's runtime and final objective value can be accessed with,
@@ -49,17 +49,17 @@ The `print_summary(result["solution"])` function can be used show an table-like
 
 ## Accessing Different Formulations
 
-The function `run_ac_opf` and `run_dc_opf` are shorthands for a more general formulation-independent OPF execution, `run_opf`.
-For example, `run_ac_opf` is equivalent to,
+The function `solve_ac_opf` and `solve_dc_opf` are shorthands for a more general formulation-independent OPF execution, `solve_opf`.
+For example, `solve_ac_opf` is equivalent to,
 
 ```julia
-run_opf("matpower/case3.m", ACPPowerModel, Ipopt.Optimizer)
+solve_opf("matpower/case3.m", ACPPowerModel, Ipopt.Optimizer)
 ```
 
-where "ACPPowerModel" indicates an AC formulation in polar coordinates.  This more generic `run_opf()` allows one to solve an OPF problem with any power network formulation implemented in PowerModels.  For example, an SOC Optimal Power Flow can be run with,
+where "ACPPowerModel" indicates an AC formulation in polar coordinates.  This more generic `solve_opf()` allows one to solve an OPF problem with any power network formulation implemented in PowerModels.  For example, an SOC Optimal Power Flow can be run with,
 
 ```julia
-run_opf("matpower/case3.m", SOCWRPowerModel, Ipopt.Optimizer)
+solve_opf("matpower/case3.m", SOCWRPowerModel, Ipopt.Optimizer)
 ```
 
 [Formulation Details](@ref) provides a list of available formulations.
@@ -72,12 +72,12 @@ The following example demonstrates one way to perform multiple PowerModels solve
 ```julia
 network_data = PowerModels.parse_file("matpower/case3.m")
 
-run_opf(network_data, ACPPowerModel, Ipopt.Optimizer)
+solve_opf(network_data, ACPPowerModel, Ipopt.Optimizer)
 
 network_data["load"]["3"]["pd"] = 0.0
 network_data["load"]["3"]["qd"] = 0.0
 
-run_opf(network_data, ACPPowerModel, Ipopt.Optimizer)
+solve_opf(network_data, ACPPowerModel, Ipopt.Optimizer)
 ```
 
 Network data parsed from PTI `.raw` files supports data extensions, i.e. data fields that are within the PSS(R)E specification, but not used by PowerModels for calculation. This can be achieved by
@@ -93,7 +93,7 @@ This network data can be modified in the same way as the previous Matpower `.m`
 
 The flow AC and DC branch results are written to the result by default. The following can be used to inspect the flow results:
 ```julia
-result = run_opf("matpower/case3_dc.m", ACPPowerModel, Ipopt.Optimizer)
+result = solve_opf("matpower/case3_dc.m", ACPPowerModel, Ipopt.Optimizer)
 result["solution"]["dcline"]["1"]
 result["solution"]["branch"]["2"]
 ```
@@ -106,7 +106,7 @@ loss_dc =  Dict(name => data["pt"]+data["pf"] for (name, data) in result["soluti
 
 
 ## Building PowerModels from Network Data Dictionaries
-The following example demonstrates how to break a `run_opf` call into separate model building and solving steps.  This allows inspection of the JuMP model created by PowerModels for the AC-OPF problem,
+The following example demonstrates how to break a `solve_opf` call into separate model building and solving steps.  This allows inspection of the JuMP model created by PowerModels for the AC-OPF problem,
 
 ```julia
 pm = instantiate_model("matpower/case3.m", ACPPowerModel, PowerModels.build_opf)

docs/src/utilities.md

@@ -7,7 +7,7 @@ This section provides an overview of the some of the utility functions that are
 To improve the quality of the convex relaxations available in PowerModels and also to obtain tightened bounds on the voltage-magnitude and phase-angle difference variables, an optimization-based bound-tightening algorithm is made available as a function in PowerModels.
 
 ```@docs
-run_obbt_opf!
+solve_obbt_opf!
 ```
 
 
@@ -16,6 +16,6 @@ run_obbt_opf!
 The following functions are meta-algorithms for solving OPF problems where line flow limit constraints are added iteratively to exploit the property that the majority of line flows constraints will be inactive in the optimal solution.
 
 ```@docs
-run_opf_branch_power_cuts
-run_opf_ptdf_branch_power_cuts
+solve_opf_branch_power_cuts
+solve_opf_ptdf_branch_power_cuts
 ```

src/PowerModels.jl

@@ -86,6 +86,114 @@ include("util/obbt.jl")
 include("util/flow_limit_cuts.jl")
 
 
+# function deprecation warnings
+# can be removed in a breaking release after 09/01/2022
+function run_model(args...; kwargs...)
+    @warn("the function run_model has been replaced with solve_model", maxlog=1)
+    solve_model(args...; kwargs...)
+end
+
+function run_pf(args...; kwargs...)
+    @warn("the function run_pf has been replaced with solve_pf", maxlog=1)
+    solve_pf(args...; kwargs...)
+end
+function run_ac_pf(args...; kwargs...)
+    @warn("the function run_ac_pf has been replaced with solve_ac_pf", maxlog=1)
+    solve_ac_pf(args...; kwargs...)
+end
+function run_dc_pf(args...; kwargs...)
+    @warn("the function run_dc_pf has been replaced with solve_dc_pf", maxlog=1)
+    solve_dc_pf(args...; kwargs...)
+end
+function run_pf_bf(args...; kwargs...)
+    @warn("the function run_pf_bf has been replaced with solve_pf_bf", maxlog=1)
+    solve_pf_bf(args...; kwargs...)
+end
+function run_pf_iv(args...; kwargs...)
+    @warn("the function run_pf_iv has been replaced with solve_pf_iv", maxlog=1)
+    solve_pf_iv(args...; kwargs...)
+end
+
+
+function run_opf(args...; kwargs...)
+    @warn("the function run_opf has been replaced with solve_opf", maxlog=1)
+    solve_opf(args...; kwargs...)
+end
+function run_ac_opf(args...; kwargs...)
+    @warn("the function run_ac_opf has been replaced with solve_ac_opf", maxlog=1)
+    solve_ac_opf(args...; kwargs...)
+end
+function run_dc_opf(args...; kwargs...)
+    @warn("the function run_dc_opf has been replaced with solve_dc_opf", maxlog=1)
+    solve_dc_opf(args...; kwargs...)
+end
+
+function run_mn_opf(args...; kwargs...)
+    @warn("the function run_mn_opf has been replaced with solve_mn_opf", maxlog=1)
+    solve_mn_opf(args...; kwargs...)
+end
+function run_mn_opf_strg(args...; kwargs...)
+    @warn("the function run_mn_opf_strg has been replaced with solve_mn_opf_strg", maxlog=1)
+    solve_mn_opf_strg(args...; kwargs...)
+end
+function run_opf_ptdf(args...; kwargs...)
+    @warn("the function run_opf_ptdf has been replaced with solve_opf_ptdf", maxlog=1)
+    solve_opf_ptdf(args...; kwargs...)
+end
+
+function run_opf_bf(args...; kwargs...)
+    @warn("the function run_opf_bf has been replaced with solve_opf_bf", maxlog=1)
+    solve_opf_bf(args...; kwargs...)
+end
+function run_mn_opf_bf_strg(args...; kwargs...)
+    @warn("the function run_mn_opf_bf_strg has been replaced with solve_mn_opf_bf_strg", maxlog=1)
+    solve_mn_opf_bf_strg(args...; kwargs...)
+end
+function run_opf_iv(args...; kwargs...)
+    @warn("the function run_opf_iv has been replaced with solve_opf_iv", maxlog=1)
+    solve_opf_iv(args...; kwargs...)
+end
+
+function run_opb(args...; kwargs...)
+    @warn("the function run_opb has been replaced with solve_opb", maxlog=1)
+    solve_opb(args...; kwargs...)
+end
+function run_nfa_opb(args...; kwargs...)
+    @warn("the function run_nfa_opb has been replaced with solve_nfa_opb", maxlog=1)
+    solve_nfa_opb(args...; kwargs...)
+end
+
+function run_ots(args...; kwargs...)
+    @warn("the function run_ots has been replaced with solve_ots", maxlog=1)
+    solve_ots(args...; kwargs...)
+end
+function run_tnep(args...; kwargs...)
+    @warn("the function run_tnep has been replaced with solve_tnep", maxlog=1)
+    solve_tnep(args...; kwargs...)
+end
+
+function run_opf_branch_power_cuts(args...; kwargs...)
+    @warn("the function run_opf_branch_power_cuts has been replaced with solve_opf_branch_power_cuts", maxlog=1)
+    solve_opf_branch_power_cuts(args...; kwargs...)
+end
+function run_opf_branch_power_cuts!(args...; kwargs...)
+    @warn("the function run_opf_branch_power_cuts! has been replaced with solve_opf_branch_power_cuts!", maxlog=1)
+    solve_opf_branch_power_cuts!(args...; kwargs...)
+end
+function run_opf_ptdf_branch_power_cuts(args...; kwargs...)
+    @warn("the function run_opf_ptdf_branch_power_cuts has been replaced with solve_opf_ptdf_branch_power_cuts", maxlog=1)
+    solve_opf_ptdf_branch_power_cuts(args...; kwargs...)
+end
+function run_opf_ptdf_branch_power_cuts!(args...; kwargs...)
+    @warn("the function run_opf_ptdf_branch_power_cuts! has been replaced with solve_opf_ptdf_branch_power_cuts!", maxlog=1)
+    solve_opf_ptdf_branch_power_cuts!(args...; kwargs...)
+end
+function run_obbt_opf!(args...; kwargs...)
+    @warn("the function run_obbt_opf! has been replaced with solve_obbt_opf!", maxlog=1)
+    solve_obbt_opf!(args...; kwargs...)
+end
+
+
 # this must come last to support automated export
 include("core/export.jl")
 

src/core/base.jl

@@ -22,13 +22,13 @@ conductor_ids(pm::AbstractPowerModel; nw::Int=nw_id_default) = pm.ref[:it][pm_it
 
 
 ""
-function run_model(file::String, model_type::Type, optimizer, build_method; kwargs...)
+function solve_model(file::String, model_type::Type, optimizer, build_method; kwargs...)
     data = PowerModels.parse_file(file)
-    return run_model(data, model_type, optimizer, build_method; kwargs...)
+    return solve_model(data, model_type, optimizer, build_method; kwargs...)
 end
 
 ""
-function run_model(data::Dict{String,<:Any}, model_type::Type, optimizer, build_method;
+function solve_model(data::Dict{String,<:Any}, model_type::Type, optimizer, build_method;
         ref_extensions=[], solution_processors=[], relax_integrality=false,
         multinetwork=false, multiconductor=false, kwargs...)