add ! to mutating data functions, progress on #454

CHANGELOG.md

@@ -2,6 +2,7 @@ PowerModels.jl Change Log
 =========================
 
 ### Staged
+- Renamed data functions to indicate when modification can occur
 - Renamed objective functions to make dcline flow costs more explicit
 
 ### Staged

docs/src/network-data.md

@@ -133,11 +133,11 @@ The PowerModels network data dictionary differs from the Matpower format in the
 
 Data exchange via JSON files is ideal for building algorithms, however it is hard to for humans to read and process.  To that end PowerModels provides various helper functions for manipulating the network data dictionary.
 
-The first of these helper functions are `make_per_unit` and `make_mixed_units`, which convert the units of the data inside a network data dictionary.  The *mixed units* format follows the unit conventions from Matpower and other common power network formats where some of the values are in per unit and others are the true values.  These functions can be used as follows,
+The first of these helper functions are `make_per_unit` and `make_mixed_units!`, which convert the units of the data inside a network data dictionary.  The *mixed units* format follows the unit conventions from Matpower and other common power network formats where some of the values are in per unit and others are the true values.  These functions can be used as follows,
 ```
 network_data = PowerModels.parse_file("matpower/case3.m")
 PowerModels.print_summary(network_data) # default per-unit form
-PowerModels.make_mixed_units(network_data)
+PowerModels.make_mixed_units!(network_data)
 PowerModels.print_summary(network_data) # mixed units form
 ```
 
@@ -147,18 +147,18 @@ data = PowerModels.parse_file("matpower/case3.m")
 opf_result = run_ac_opf(data, JuMP.with_optimizer(Ipopt.Optimizer))
 PowerModels.print_summary(opf_result["solution"])
 
-PowerModels.update_data(data, opf_result["solution"])
+PowerModels.update_data!(data, opf_result["solution"])
 pf_result = run_ac_pf(data, JuMP.with_optimizer(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,
+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)
+PowerModels.propagate_topology_status!(data)
 opf_result = run_ac_opf(data, JuMP.with_optimizer(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 `propagate_topology_status` function can be helpful in diagnosing network models that converge to an infeasible solution.
+The `test/data/matpower/case7_tplgy.m` case provides an example of the kind of component status deductions that can be made.  The `propagate_topology_status!` function can be helpful in diagnosing network models that converge to an infeasible solution.
 
 For details on all of the network data helper functions see, `src/core/data.jl`.
 

docs/src/result-data.md

@@ -81,10 +81,10 @@ PowerModels.print_summary(result["solution"])
 ```
 
 Because the data dictionary and the solution dictionary have the same structure
-PowerModels provides an `update_data` helper function which can be used to
+PowerModels provides an `update_data!` helper function which can be used to
 update a data dictionary with the values from a solution as follows,
 
 ```
-PowerModels.update_data(data, result["solution"])
+PowerModels.update_data!(data, result["solution"])
 ```