From a2dff8aa85d14e450a8a8e46f1c90a01f1defa3e Mon Sep 17 00:00:00 2001 From: annacasavant Date: Wed, 20 Nov 2024 17:00:05 -0700 Subject: [PATCH 1/6] updated get_components. --- docs/make.jl | 1 + docs/src/tutorials/get_component_data.md | 122 ----------- docs/src/tutorials/manipulating_datasets.md | 213 ++++++++++++++++++++ 3 files changed, 214 insertions(+), 122 deletions(-) delete mode 100644 docs/src/tutorials/get_component_data.md create mode 100644 docs/src/tutorials/manipulating_datasets.md diff --git a/docs/make.jl b/docs/make.jl index 22d9d288d6..698a1f744c 100644 --- a/docs/make.jl +++ b/docs/make.jl @@ -13,6 +13,7 @@ pages = OrderedDict( "Create and Explore a Power `System`" => "tutorials/creating_system.md", "Working with Time Series" => "tutorials/working_with_time_series.md", "Adding Data for Dynamic Simulations" => "tutorials/add_dynamic_data.md", + "Manipulating Data Sets" => "tutorials/manipulating_datasets.md" ], "How to..." => Any[ "...install PowerSystems.jl" => "how_to/install.md", diff --git a/docs/src/tutorials/get_component_data.md b/docs/src/tutorials/get_component_data.md deleted file mode 100644 index 8aa4403795..0000000000 --- a/docs/src/tutorials/get_component_data.md +++ /dev/null @@ -1,122 +0,0 @@ -# [Getting, Setting, and Viewing Data](@id get_components_tutorial ) - -In this tutorial, we will explore the data in a `System`, including looking at a summary of -the system and getting both its components and their data. We will also start checking for -time-series data, which we will explore more in the tutorial on -[Working with Time Series Data](@ref tutorial_time_series). - -In [Create and Explore a Power `System`](@ref), we created a basic `System` with nodes, a transmission -line, and a few generators. Let's recreate that system if you don't have it already: - -```@setup get_component_data -using PowerSystems; -sys = System(100.0); -bus1 = ACBus(1, "bus1", ACBusTypes.REF, 0.0, 1.0, (min = 0.9, max = 1.05), 230.0); -bus2 = ACBus(2, "bus2", ACBusTypes.PV, 0.0, 1.0, (min = 0.9, max = 1.05), 230.0); - -``` - -PowerSystems provides functional interfaces to all data. The following examples outline -the intended approach to accessing data expressed using PowerSystems. - -PowerSystems enforces unique `name` fields between components of a particular concrete type. -So, in order to retrieve a specific component, the user must specify the type of the component -along with the name and system - -#### Accessing components and their data - -```@repl get_components -get_component(ACBus, sys, "nodeA") -get_component(Line, sys, "1") -``` - -Similarly, you can access all the components of a particular type: *note: the return type -of get_components is a `FlattenIteratorWrapper`, so call `collect` to get an `Array` - -```@repl get_components -get_components(ACBus, sys) |> collect -``` - -`get_components` also works on abstract types: - -```@repl get_components -get_components(Branch, sys) |> collect -``` - -The fields within a component can be accessed using the `get_*` functions: -*It's highly recommended that users avoid using the `.` to access fields since we make no -guarantees on the stability field names and locations. We do however promise to keep the -accessor functions stable.* - -```@repl get_components -bus1 = get_component(ACBus, sys, "nodeA") -@show get_name(bus1); -@show get_magnitude(bus1); -nothing #hide -``` - -## Accessing components stored in the system - - -```@repl system -using PowerSystems -file_dir = joinpath(pkgdir(PowerSystems), "docs", "src", "tutorials", "tutorials_data") -system = System(joinpath(file_dir, "RTS_GMLC.m")); -thermal_gens = get_components(ThermalStandard, system) -``` - -It is also possible to execute [`get_components`](@ref) with abstract types from the -[abstract tree](@ref type_structure). For instance, it is possible to retrieve all renewable -generators - -```@repl system -thermal_gens = get_components(RenewableGen, system) -``` - -The most common filtering requirement is by component name and for this case the method -[`get_component`](@ref) returns a single component taking the device type, system and name as arguments. - -```@repl system -my_thermal_gen = get_component(ThermalStandard, system, "323_CC_1") -``` - -## Accessing data stored in a component - -__Using the "dot" access to get a parameter value from a component is actively discouraged, use "getter" functions instead__ - - -For example, the `my_thermal_gen.active_power_limits` parameter of a thermal generator should be accessed as follows: - -```@repl system -get_active_power_limits(my_thermal_gen) -``` - -You can also view data from all instances of a concrete type in one table with the function `show_components`. It provides a few options: - - 1. View the standard fields by accepting the defaults. - 2. Pass a dictionary where the keys are column names and the values are functions that accept a component as a single argument. - 3. Pass a vector of symbols that are field names of the type. - -```@repl system -show_components(system, ThermalStandard) -show_components(system, ThermalStandard, Dict("has_time_series" => x -> has_time_series(x))) -show_components(system, ThermalStandard, [:active_power, :reactive_power]) -``` - -# to do: add a link in the system that MD explanation to these examples diff --git a/docs/src/tutorials/manipulating_datasets.md b/docs/src/tutorials/manipulating_datasets.md new file mode 100644 index 0000000000..0eeabd5504 --- /dev/null +++ b/docs/src/tutorials/manipulating_datasets.md @@ -0,0 +1,213 @@ +# Manipulating Data Sets + +`PowerSystems` provides function interfaces to all data, and in this tutorial we will explore how to do this using the `get_*`, `set_*`, and `show_components` functions. + +!!! note "Understanding the Behavior of Getters and Setters" + `PowerSystems` returns Julia iterators in order to avoid unnecessary memory allocations. The `get_components` function returns an iterator that loops through data fields to access specific parameters. The `set_*` function uses an iterator like `get_components` to manipulate specific parameters of components. + +## Viewing Components in the System +We are going to begin by loading in a test case from the [`PowerSystemCaseBuilder.jl`](https://nrel-sienna.github.io/PowerSystems.jl/stable/how_to/powersystembuilder/#psb): +```@repl system +using PowerSystems; +using PowerSystemCaseBuilder; +sys = build_system(PSISystems, "c_sys5_pjm") +``` + +We can use the [`show_components`](@ref) function to view data in our system. Let's start by viewing all of the [`ThermalStandard`](@ref) components in the system. + +```@repl system +show_components(ThermalStandard, sys) +``` +We can see there are five thermal generators in the system. +Similarly we can see all of the [`ACBus`](@ref) components in our system. +```@repl system +show_components(ACBus, sys) +``` +Notice in both the [`ACBus`](@ref) example and [`ThermalStandard`](@ref) example, a table with the name and availability are returned. The availability is the standard parameter returned when using [`show_components`](@ref). + +We can also view specific parameters within components using the [`show_components`](@ref) function. For example, we can view the type of [`fuel`](@reftf_list) the thermal generators are using: +```@repl system +show_components(ThermalStandard, sys, [:fuel]) +``` +If we were interested in viewing more than one parameter, like the `active power` and `reactive power` of the thermal generators: +```@repl system +show_components(ThermalStandard, sys, [:active_power, :reactive_power]) +``` +We can see a table is returned with both `active_power` and `reactive_power`. +## Accessing and Updating a Component in a System +We can access a component in our system using the [`get_component`](@ref) function. For example, if we are interested in accessing a [`ThermalStandard`](@ref) component in the system we can do so using the component [`type`](@id type_structure) and name. From above we know the names of the thermal generators. +```@repl system +solitude = get_component(ThermalStandard, sys, "Solitude") +``` + + +The parameters associated with that generator should be returned. If we are interested in accessing a particular parameter of that generator we can use a `get_*` function. For example, if we are interested in the [`fuel`](@reftf_list) we can use [`get_fuel`](@ref) +```@repl system +get_fuel(solitude) +``` +You should see the [`fuel`](@reftf_list) parameter returned. + +To recap, [`get_component`](@ref) will return all parameters of a specific componenet, but we can use a specific `get_*` function to return a particular parameter. + +To update a parameter we can use a specific `set_*` function. We can use [`set_fuel!`](@ref) to update the fuel parameter of Solitude to natural gas. +```@repl system +set_fuel!(solitude, ThermalFuels.NATURAL_GAS) +``` +We can check that the `Solitude` fuel has been updated to `ThermalFuels.AG_BIPRODUCT`: +```@repl system +show_components(ThermalStandard, sys, [:fuel]) +``` +Another example of using a specific `get_*` function and `set_*` function is when you are updating the `active_power` parameter. We can access this parameter by using the [`get_active_power`](@ref): +```@repl system +get_active_power(solitude) +``` +We can then update it using [`set_active_power!`](@ref): +```@repl system +set_active_power!(solitude, 4.0) +``` +We can see that our `active_power` parameter has been updated to 4.0. + + +## Accessing and Updating Multiple Components in the System at Once +We can also update more than one component at a time using the [`get_components`](@ref) and `set_*` functions. + +Let's say we were interested in updating the `base_voltage` parameter for all of the [`ACBus`](@ref) components. We can see that currently the `base_voltages` are: +```@repl system +show_components(ACBus, sys, [:base_voltage]) +``` +But what if we are looking to change them to 250.0? Let's start by getting an iterator for all the buses using [`get_components`](@ref): +```@repl system +buses = get_components(ACBus, sys) +``` +Now using the [`set_base_voltage!`](@ref) function and a `for loop` we can update the voltage: +```@repl system +for i in buses +set_base_voltage!(i, 250.0) +end +``` +We can see that all of the buses now have a `base_voltage` of 250.0: +```@repl system +show_components(ACBus, sys, [:base_voltage]) +``` +If we were interested in updating the fuel in all the thermal generators, we would use a similar approach. We begin by grabbing an iterator for all the components in `ThermalStandard`. +```@repl system +thermal_gens = get_components(ThermalStandard, sys) +``` +Now, using a the [`set_fuel!`](https://nrel-sienna.github.io/PowerSystems.jl/stable/model_library/generated_ThermalStandard/#PowerSystems.set_fuel!-Tuple{ThermalStandard,%20Any}) and a for loop, we will update the fuel to `NATURAL_GAS`. +```@repl system +for i in thermal_gens +set_fuel!(i, ThermalFuels.NATURAL_GAS) +end +``` +We can see that all the fuel type for all the thermal gens has been updated. +```@repl system +show_components(ThermalStandard, sys, [:fuel]) +``` +We can also use a dot operator with a specific `get_*` function and the [`get_components`](@ref) function to return a vector of parameters for multiple components: +```@repl system +get_fuel.(get_components(ThermalStandard, sys)) +``` + +## Filtering Specific Data +We have seen how to update a single component, and all the components of a specific type, but what if we are interested in updating particular components? We can do this using filter functions. For example, let's say we are interested in updating all the `active_power` parameters of the thermal generators except `Solitude`. + +Let's start by seeing the current `active_power` parameters. +```@repl system +show_components(ThermalStandard, sys, [:active_power]) +``` +Let's grab an iterator for the all the thermal generators except `Solitdue` using a filter function: +```@repl system +thermal_not_solitude = get_components(x -> get_name(x) != "Solitude", ThermalStandard, sys) +``` +We can see that four `ThermalStandard` components are returned. Now let's update the `active_power` parameter of these four thermal generators using the [`set_active_power`](https://nrel-sienna.github.io/PowerSystems.jl/stable/model_library/generated_EnergyReservoirStorage/#PowerSystems.set_active_power!-Tuple{EnergyReservoirStorage,%20Any}) function. +```@repl system +for i in thermal_not_solitude +set_active_power!(i, 0.0) +end +``` +Let's check the update using `show_components`: +```@repl system +show_components(ThermalStandard, sys, [:active_power]) +``` +We can see that all the `active_power` parameters are 0.0, except sundance. + +We can also filter using parameter values. For example, we can access all the thermal generators that have ratings of either 5.2 or 0.5: +```@repl system +show_components(ThermalStandard, sys, [:rating]) +``` +We can see that `Solitude` has a rating of 5.2 and `Alta` has a rating of 0.5. +```@repl system +thermal_rating = get_components(x -> get_rating(x) == 5.2 || get_rating(x) == 0.5, ThermalStandard, sys ) +``` +We can see that two components are returned. If we wanted to update those ratings to 4.0: +```@repl system +for i in thermal_rating +set_rating!(i, 4.0) +end +``` +The rating parameters of `Solitude` and `Alta` are now 4.0: +```@repl system +show_components(ThermalStandard, sys, [:rating]) +``` + +## Getting Available Components +The [`get_available_components`](@ref) function allows us to grab all the components of a particular type that are available. For example, if we were interested in grabbing all the available renewable generators: +```@repl system +get_available_components(RenewableDispatch, sys) +``` +The two `RenewableDispatch` components are returned because they are available. + +We can update the availability of components using the [`set_available!`](@ref) function. Let's filter all of the thermal generators that have an `active_power` of 0.0, and set their availability to false. +```@repl system +not_available = get_components(x -> get_active_power(x) == 0.0, ThermalStandard, sys) +``` +```@repl system +for i in not_available +set_available!(i, 0) +end +``` +Let's check the availability of our [`ThermalStandard`](@ref) components. +```@repl system +show_components(ThermalStandard, sys) +``` +Recall that the default columns returned when using [`show_components`](@ref) are the name and availability. + +## Getting Buses +We can access the [`ACbus`](@ref) components in the system using the [`get_buses`](@ref) function. There are multiple approaches to using this function, but in this tutorial we are going to focus on getting buses using the ID numbers. +Let's begin by accessing the ID numbers associated with the [`ACBus`](@ref) components using the [`get_bus_numbers`](@ref) function. +```@repl system +get_bus_numbers(sys) +``` +We can see that a vector of values 1:5 is returned. Now let's grab the buses using the [`get_buses`](@ref) function. +```@repl system +get_buses(sys, Set(1:5)) +``` +The 5 buses in the system are returned. +## Updating Component Names +When we are updating a component name using the function [`set_name!`](@ref) it is important to note that this not only changes the field `name`, but also changes the container itself. + +Recall that we created an iterator called `thermal_gens` for all the thermal generators. We can use the [`get_name`](@ref) function to access the `name` parameter for these components. +```@repl system +for i in thermal_gens +@show get_name(i) +end +``` +To update the names we will use the [`set_name`](@ref) function. However, it is important to note that using [`set_name`](@ref) not only changes the field `name`, but also changes the container itself. Therefore, it is important that it is important to do the following: +```@repl system +for thermal_gen in collect(get_components(ThermalStandard, sys)) + set_name!(sys, thermal_gen, get_name(thermal_gen)*"-renamed") +end +``` +Now we can check the names using the [`get_name`](@ref) function again. +```@repl system +get_name.(get_components(ThermalStandard,sys)) +``` +!!! warning + Using the "dot" access to get a parameter value from a component is actively discouraged, use `get_*` functions instead. Julia syntax enables access to this data using the "dot" access, however this is discouraged for two reasons: + 1. We make no guarantees on the stability of component structure definitions. We will maintain version stability on the accessor methods. + 2. Per-unit conversions are made in the return of data from the accessor functions. (see the [per-unit](https://nrel-sienna.github.io/PowerSystems.jl/stable/explanation/per_unit/#per_unit) section for more details) + + +## Next Steps & Links +So far we have seen that we can view different data types in our system using the `show_components` function, we can can access those types using the `get_*` function, and we can manipulate them using `set_*`. +Follow the next tutorials to learn how to [work with time series](https://nrel-sienna.github.io/PowerSystems.jl/stable/tutorials/working_with_time_series/). \ No newline at end of file From a2af2b9a4b723d8fd2cca7aadf91cb2557643d3c Mon Sep 17 00:00:00 2001 From: annacasavant Date: Fri, 22 Nov 2024 09:02:11 -0700 Subject: [PATCH 2/6] Grammar Fixes --- docs/src/tutorials/manipulating_datasets.md | 52 ++++++++++----------- 1 file changed, 26 insertions(+), 26 deletions(-) diff --git a/docs/src/tutorials/manipulating_datasets.md b/docs/src/tutorials/manipulating_datasets.md index 0eeabd5504..26918b40e2 100644 --- a/docs/src/tutorials/manipulating_datasets.md +++ b/docs/src/tutorials/manipulating_datasets.md @@ -1,4 +1,4 @@ -# Manipulating Data Sets +# Manipulating Datasets `PowerSystems` provides function interfaces to all data, and in this tutorial we will explore how to do this using the `get_*`, `set_*`, and `show_components` functions. @@ -13,13 +13,13 @@ using PowerSystemCaseBuilder; sys = build_system(PSISystems, "c_sys5_pjm") ``` -We can use the [`show_components`](@ref) function to view data in our system. Let's start by viewing all of the [`ThermalStandard`](@ref) components in the system. +We can use the [`show_components`](@ref) function to view data in our system. Let's start by viewing all of the [`ThermalStandard`](@ref) components. ```@repl system show_components(ThermalStandard, sys) ``` We can see there are five thermal generators in the system. -Similarly we can see all of the [`ACBus`](@ref) components in our system. +Similarly, we can see all the [`ACBus`](@ref) components in the system. ```@repl system show_components(ACBus, sys) ``` @@ -29,25 +29,24 @@ We can also view specific parameters within components using the [`show_componen ```@repl system show_components(ThermalStandard, sys, [:fuel]) ``` -If we were interested in viewing more than one parameter, like the `active power` and `reactive power` of the thermal generators: +If we are interested in viewing more than one parameter, like the `active power` and `reactive power` of the thermal generators: ```@repl system show_components(ThermalStandard, sys, [:active_power, :reactive_power]) ``` We can see a table is returned with both `active_power` and `reactive_power`. ## Accessing and Updating a Component in a System -We can access a component in our system using the [`get_component`](@ref) function. For example, if we are interested in accessing a [`ThermalStandard`](@ref) component in the system we can do so using the component [`type`](@id type_structure) and name. From above we know the names of the thermal generators. +We can access a component in our system using the [`get_component`](@ref) function. For example, if we are interested in accessing a [`ThermalStandard`](@ref) component we can do so using the component [`type`](@id type_structure) and name. From above we know the names of the thermal generators. ```@repl system solitude = get_component(ThermalStandard, sys, "Solitude") ``` - -The parameters associated with that generator should be returned. If we are interested in accessing a particular parameter of that generator we can use a `get_*` function. For example, if we are interested in the [`fuel`](@reftf_list) we can use [`get_fuel`](@ref) +Notice, the parameters associated with that generator are returned. If we are interested in accessing a particular parameter of that generator we can use a `get_*` function. For example, if we are interested in the [`fuel`](@reftf_list) we can use [`get_fuel`](@ref) ```@repl system get_fuel(solitude) ``` You should see the [`fuel`](@reftf_list) parameter returned. -To recap, [`get_component`](@ref) will return all parameters of a specific componenet, but we can use a specific `get_*` function to return a particular parameter. +To recap, [`get_component`](@ref) will return all parameters of a component, but we can use a specific `get_*` function to return a particular parameter. To update a parameter we can use a specific `set_*` function. We can use [`set_fuel!`](@ref) to update the fuel parameter of Solitude to natural gas. ```@repl system @@ -67,7 +66,6 @@ set_active_power!(solitude, 4.0) ``` We can see that our `active_power` parameter has been updated to 4.0. - ## Accessing and Updating Multiple Components in the System at Once We can also update more than one component at a time using the [`get_components`](@ref) and `set_*` functions. @@ -89,17 +87,17 @@ We can see that all of the buses now have a `base_voltage` of 250.0: ```@repl system show_components(ACBus, sys, [:base_voltage]) ``` -If we were interested in updating the fuel in all the thermal generators, we would use a similar approach. We begin by grabbing an iterator for all the components in `ThermalStandard`. +If we are interested in updating the fuel in all the thermal generators, we would use a similar approach. We begin by grabbing an iterator for all the components in [`ThermalStandard`](@ref). ```@repl system thermal_gens = get_components(ThermalStandard, sys) ``` -Now, using a the [`set_fuel!`](https://nrel-sienna.github.io/PowerSystems.jl/stable/model_library/generated_ThermalStandard/#PowerSystems.set_fuel!-Tuple{ThermalStandard,%20Any}) and a for loop, we will update the fuel to `NATURAL_GAS`. +Now, using the [`set_fuel!`](@ref) and a for loop, we will update the fuel to `NATURAL_GAS`. ```@repl system for i in thermal_gens set_fuel!(i, ThermalFuels.NATURAL_GAS) end ``` -We can see that all the fuel type for all the thermal gens has been updated. +We can see that the fuel types for all the thermal generators has been updated. ```@repl system show_components(ThermalStandard, sys, [:fuel]) ``` @@ -107,29 +105,33 @@ We can also use a dot operator with a specific `get_*` function and the [`get_co ```@repl system get_fuel.(get_components(ThermalStandard, sys)) ``` +Notice that the fuel type for all the thermal generators is returned. +!!! warning + Using the "dot" access to get a parameter value from a component is actively discouraged, use `get_*` functions instead. Julia syntax enables access to this data using the "dot" access, however this is discouraged for two reasons: + 1. We make no guarantees on the stability of component structure definitions. We will maintain version stability on the accessor methods. + 2. Per-unit conversions are made in the return of data from the accessor functions. (see the [per-unit](https://nrel-sienna.github.io/PowerSystems.jl/stable/explanation/per_unit/#per_unit) section for more details) ## Filtering Specific Data We have seen how to update a single component, and all the components of a specific type, but what if we are interested in updating particular components? We can do this using filter functions. For example, let's say we are interested in updating all the `active_power` parameters of the thermal generators except `Solitude`. - Let's start by seeing the current `active_power` parameters. ```@repl system show_components(ThermalStandard, sys, [:active_power]) ``` -Let's grab an iterator for the all the thermal generators except `Solitdue` using a filter function: +Let's grab an iterator for the all the thermal generators except `Solitude` using a filter function: ```@repl system thermal_not_solitude = get_components(x -> get_name(x) != "Solitude", ThermalStandard, sys) ``` -We can see that four `ThermalStandard` components are returned. Now let's update the `active_power` parameter of these four thermal generators using the [`set_active_power`](https://nrel-sienna.github.io/PowerSystems.jl/stable/model_library/generated_EnergyReservoirStorage/#PowerSystems.set_active_power!-Tuple{EnergyReservoirStorage,%20Any}) function. +We can see that four [`ThermalStandard`](@ref) components are returned. Now let's update the `active_power` parameter of these four thermal generators using the [`set_active_power`](@ref) function. ```@repl system for i in thermal_not_solitude set_active_power!(i, 0.0) end ``` -Let's check the update using `show_components`: +Let's check the update using [`show_components`](@ref): ```@repl system show_components(ThermalStandard, sys, [:active_power]) ``` -We can see that all the `active_power` parameters are 0.0, except sundance. +We can see that all the `active_power` parameters are 0.0, except `Solitude`. We can also filter using parameter values. For example, we can access all the thermal generators that have ratings of either 5.2 or 0.5: ```@repl system @@ -151,11 +153,11 @@ show_components(ThermalStandard, sys, [:rating]) ``` ## Getting Available Components -The [`get_available_components`](@ref) function allows us to grab all the components of a particular type that are available. For example, if we were interested in grabbing all the available renewable generators: +The [`get_available_components`](@ref) function allows us to grab all the components of a particular type that are available. For example, if we are interested in grabbing all the available renewable generators: ```@repl system get_available_components(RenewableDispatch, sys) ``` -The two `RenewableDispatch` components are returned because they are available. +The two [`RenewableDispatch`](@ref) components are returned because they are available. We can update the availability of components using the [`set_available!`](@ref) function. Let's filter all of the thermal generators that have an `active_power` of 0.0, and set their availability to false. ```@repl system @@ -183,16 +185,18 @@ We can see that a vector of values 1:5 is returned. Now let's grab the buses usi get_buses(sys, Set(1:5)) ``` The 5 buses in the system are returned. + ## Updating Component Names -When we are updating a component name using the function [`set_name!`](@ref) it is important to note that this not only changes the field `name`, but also changes the container itself. +We can also access and update the component name parameter using the [`get_name](@ref) and [`set_name!`](@ref) functions. + Recall that we created an iterator called `thermal_gens` for all the thermal generators. We can use the [`get_name`](@ref) function to access the `name` parameter for these components. ```@repl system for i in thermal_gens @show get_name(i) end ``` -To update the names we will use the [`set_name`](@ref) function. However, it is important to note that using [`set_name`](@ref) not only changes the field `name`, but also changes the container itself. Therefore, it is important that it is important to do the following: +To update the names we will use the [`set_name`](@ref) function. However, it is important to note that using [`set_name`](@ref) not only changes the field `name`, but also changes the container itself. Therefore, it is crucial to do the following: ```@repl system for thermal_gen in collect(get_components(ThermalStandard, sys)) set_name!(sys, thermal_gen, get_name(thermal_gen)*"-renamed") @@ -202,12 +206,8 @@ Now we can check the names using the [`get_name`](@ref) function again. ```@repl system get_name.(get_components(ThermalStandard,sys)) ``` -!!! warning - Using the "dot" access to get a parameter value from a component is actively discouraged, use `get_*` functions instead. Julia syntax enables access to this data using the "dot" access, however this is discouraged for two reasons: - 1. We make no guarantees on the stability of component structure definitions. We will maintain version stability on the accessor methods. - 2. Per-unit conversions are made in the return of data from the accessor functions. (see the [per-unit](https://nrel-sienna.github.io/PowerSystems.jl/stable/explanation/per_unit/#per_unit) section for more details) ## Next Steps & Links -So far we have seen that we can view different data types in our system using the `show_components` function, we can can access those types using the `get_*` function, and we can manipulate them using `set_*`. +So far we have seen that we can view different data types in our system using the `show_components` function, we can access those types using the `get_*` function, and we can manipulate them using the `set_*` functions. Follow the next tutorials to learn how to [work with time series](https://nrel-sienna.github.io/PowerSystems.jl/stable/tutorials/working_with_time_series/). \ No newline at end of file From 9313e5a654ac899fe2eacff69d158d5bcc4d8c76 Mon Sep 17 00:00:00 2001 From: annacasavant Date: Fri, 22 Nov 2024 09:12:56 -0700 Subject: [PATCH 3/6] grammar --- docs/src/tutorials/manipulating_datasets.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/src/tutorials/manipulating_datasets.md b/docs/src/tutorials/manipulating_datasets.md index 26918b40e2..a855484fb9 100644 --- a/docs/src/tutorials/manipulating_datasets.md +++ b/docs/src/tutorials/manipulating_datasets.md @@ -25,7 +25,7 @@ show_components(ACBus, sys) ``` Notice in both the [`ACBus`](@ref) example and [`ThermalStandard`](@ref) example, a table with the name and availability are returned. The availability is the standard parameter returned when using [`show_components`](@ref). -We can also view specific parameters within components using the [`show_components`](@ref) function. For example, we can view the type of [`fuel`](@reftf_list) the thermal generators are using: +We can also view specific parameters within components using the [`show_components`](@ref) function. For example, we can view the type of [`fuel`](@id tf_list) the thermal generators are using: ```@repl system show_components(ThermalStandard, sys, [:fuel]) ``` @@ -35,7 +35,7 @@ show_components(ThermalStandard, sys, [:active_power, :reactive_power]) ``` We can see a table is returned with both `active_power` and `reactive_power`. ## Accessing and Updating a Component in a System -We can access a component in our system using the [`get_component`](@ref) function. For example, if we are interested in accessing a [`ThermalStandard`](@ref) component we can do so using the component [`type`](@id type_structure) and name. From above we know the names of the thermal generators. +We can access a component in our system using the [`get_component`](@ref) function. For example, if we are interested in accessing a [`ThermalStandard`](@ref) component we can do so using the component [`type`](https://nrel-sienna.github.io/PowerSystems.jl/stable/api/type_tree/) and name. From above we know the names of the thermal generators. ```@repl system solitude = get_component(ThermalStandard, sys, "Solitude") ``` @@ -188,7 +188,7 @@ The 5 buses in the system are returned. ## Updating Component Names -We can also access and update the component name parameter using the [`get_name](@ref) and [`set_name!`](@ref) functions. +We can also access and update the component name parameter using the [`get_name`](@ref) and [`set_name!`](@ref) functions. Recall that we created an iterator called `thermal_gens` for all the thermal generators. We can use the [`get_name`](@ref) function to access the `name` parameter for these components. ```@repl system From 7a886932c8f2867efed8e89d336d3efdd5123157 Mon Sep 17 00:00:00 2001 From: annacasavant Date: Fri, 22 Nov 2024 09:19:07 -0700 Subject: [PATCH 4/6] removed fuel (@ref) --- docs/src/tutorials/manipulating_datasets.md | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/docs/src/tutorials/manipulating_datasets.md b/docs/src/tutorials/manipulating_datasets.md index a855484fb9..90aad63d89 100644 --- a/docs/src/tutorials/manipulating_datasets.md +++ b/docs/src/tutorials/manipulating_datasets.md @@ -25,7 +25,7 @@ show_components(ACBus, sys) ``` Notice in both the [`ACBus`](@ref) example and [`ThermalStandard`](@ref) example, a table with the name and availability are returned. The availability is the standard parameter returned when using [`show_components`](@ref). -We can also view specific parameters within components using the [`show_components`](@ref) function. For example, we can view the type of [`fuel`](@id tf_list) the thermal generators are using: +We can also view specific parameters within components using the [`show_components`](@ref) function. For example, we can view the type of `fuel` the thermal generators are using: ```@repl system show_components(ThermalStandard, sys, [:fuel]) ``` @@ -40,19 +40,19 @@ We can access a component in our system using the [`get_component`](@ref) functi solitude = get_component(ThermalStandard, sys, "Solitude") ``` -Notice, the parameters associated with that generator are returned. If we are interested in accessing a particular parameter of that generator we can use a `get_*` function. For example, if we are interested in the [`fuel`](@reftf_list) we can use [`get_fuel`](@ref) +Notice, the parameters associated with that generator are returned. If we are interested in accessing a particular parameter of that generator we can use a `get_*` function. For example, if we are interested in the `fuel` we can use [`get_fuel`](@ref) ```@repl system get_fuel(solitude) ``` -You should see the [`fuel`](@reftf_list) parameter returned. +You should see the `fuel` parameter returned. To recap, [`get_component`](@ref) will return all parameters of a component, but we can use a specific `get_*` function to return a particular parameter. -To update a parameter we can use a specific `set_*` function. We can use [`set_fuel!`](@ref) to update the fuel parameter of Solitude to natural gas. +To update a parameter we can use a specific `set_*` function. We can use [`set_fuel!`](@ref) to update the `fuel` parameter of Solitude to natural gas. ```@repl system set_fuel!(solitude, ThermalFuels.NATURAL_GAS) ``` -We can check that the `Solitude` fuel has been updated to `ThermalFuels.AG_BIPRODUCT`: +We can check that the `Solitude` `fuel` has been updated to `ThermalFuels.AG_BIPRODUCT`: ```@repl system show_components(ThermalStandard, sys, [:fuel]) ``` @@ -87,17 +87,17 @@ We can see that all of the buses now have a `base_voltage` of 250.0: ```@repl system show_components(ACBus, sys, [:base_voltage]) ``` -If we are interested in updating the fuel in all the thermal generators, we would use a similar approach. We begin by grabbing an iterator for all the components in [`ThermalStandard`](@ref). +If we are interested in updating the `fuel` in all the thermal generators, we would use a similar approach. We begin by grabbing an iterator for all the components in [`ThermalStandard`](@ref). ```@repl system thermal_gens = get_components(ThermalStandard, sys) ``` -Now, using the [`set_fuel!`](@ref) and a for loop, we will update the fuel to `NATURAL_GAS`. +Now, using the [`set_fuel!`](@ref) and a for loop, we will update the `fuel` to `NATURAL_GAS`. ```@repl system for i in thermal_gens set_fuel!(i, ThermalFuels.NATURAL_GAS) end ``` -We can see that the fuel types for all the thermal generators has been updated. +We can see that the `fuel` types for all the thermal generators has been updated. ```@repl system show_components(ThermalStandard, sys, [:fuel]) ``` @@ -105,7 +105,7 @@ We can also use a dot operator with a specific `get_*` function and the [`get_co ```@repl system get_fuel.(get_components(ThermalStandard, sys)) ``` -Notice that the fuel type for all the thermal generators is returned. +Notice that the `fuel` type for all the thermal generators is returned. !!! warning Using the "dot" access to get a parameter value from a component is actively discouraged, use `get_*` functions instead. Julia syntax enables access to this data using the "dot" access, however this is discouraged for two reasons: 1. We make no guarantees on the stability of component structure definitions. We will maintain version stability on the accessor methods. From 11a2144fcfe286f784e838016bf1a3a4f6c72787 Mon Sep 17 00:00:00 2001 From: annacasavant Date: Fri, 22 Nov 2024 10:56:06 -0700 Subject: [PATCH 5/6] fixing (@ref) --- docs/src/tutorials/manipulating_datasets.md | 21 +++++++++++++-------- 1 file changed, 13 insertions(+), 8 deletions(-) diff --git a/docs/src/tutorials/manipulating_datasets.md b/docs/src/tutorials/manipulating_datasets.md index 90aad63d89..c0baff0868 100644 --- a/docs/src/tutorials/manipulating_datasets.md +++ b/docs/src/tutorials/manipulating_datasets.md @@ -19,11 +19,13 @@ We can use the [`show_components`](@ref) function to view data in our system. Le show_components(ThermalStandard, sys) ``` We can see there are five thermal generators in the system. -Similarly, we can see all the [`ACBus`](@ref) components in the system. +Similarly, we can see all the [`ACBus`](@ref), notice that we need define some basic data, including the bus's + components in the system. ```@repl system show_components(ACBus, sys) ``` -Notice in both the [`ACBus`](@ref) example and [`ThermalStandard`](@ref) example, a table with the name and availability are returned. The availability is the standard parameter returned when using [`show_components`](@ref). +Notice in both the [`ACBus`](@ref), notice that we need define some basic data, including the bus's + example and [`ThermalStandard`](@ref) example, a table with the name and availability are returned. The availability is the standard parameter returned when using [`show_components`](@ref). We can also view specific parameters within components using the [`show_components`](@ref) function. For example, we can view the type of `fuel` the thermal generators are using: ```@repl system @@ -69,7 +71,8 @@ We can see that our `active_power` parameter has been updated to 4.0. ## Accessing and Updating Multiple Components in the System at Once We can also update more than one component at a time using the [`get_components`](@ref) and `set_*` functions. -Let's say we were interested in updating the `base_voltage` parameter for all of the [`ACBus`](@ref) components. We can see that currently the `base_voltages` are: +Let's say we were interested in updating the `base_voltage` parameter for all of the [`ACBus`](@ref), notice that we need define some basic data, including the bus's + components. We can see that currently the `base_voltages` are: ```@repl system show_components(ACBus, sys, [:base_voltage]) ``` @@ -121,7 +124,7 @@ Let's grab an iterator for the all the thermal generators except `Solitude` usin ```@repl system thermal_not_solitude = get_components(x -> get_name(x) != "Solitude", ThermalStandard, sys) ``` -We can see that four [`ThermalStandard`](@ref) components are returned. Now let's update the `active_power` parameter of these four thermal generators using the [`set_active_power`](@ref) function. +We can see that four [`ThermalStandard`](@ref) components are returned. Now let's update the `active_power` parameter of these four thermal generators using the [`set_active_power!`](@ref) function. ```@repl system for i in thermal_not_solitude set_active_power!(i, 0.0) @@ -175,8 +178,10 @@ show_components(ThermalStandard, sys) Recall that the default columns returned when using [`show_components`](@ref) are the name and availability. ## Getting Buses -We can access the [`ACbus`](@ref) components in the system using the [`get_buses`](@ref) function. There are multiple approaches to using this function, but in this tutorial we are going to focus on getting buses using the ID numbers. -Let's begin by accessing the ID numbers associated with the [`ACBus`](@ref) components using the [`get_bus_numbers`](@ref) function. +We can access the [`ACBus]`(@ref), notice that we need define some basic data, including the bus's + components in the system using the [`get_buses`](@ref) function. There are multiple approaches to using this function, but in this tutorial we are going to focus on getting buses using the ID numbers. +Let's begin by accessing the ID numbers associated with the [`ACBus`](@ref), notice that we need define some basic data, including the bus's + components using the [`get_bus_numbers`](@ref) function. ```@repl system get_bus_numbers(sys) ``` @@ -188,7 +193,7 @@ The 5 buses in the system are returned. ## Updating Component Names -We can also access and update the component name parameter using the [`get_name`](@ref) and [`set_name!`](@ref) functions. +We can also access and update the component name parameter using the [`get_name`](@ref) and [set_name!](@ref) functions. Recall that we created an iterator called `thermal_gens` for all the thermal generators. We can use the [`get_name`](@ref) function to access the `name` parameter for these components. ```@repl system @@ -196,7 +201,7 @@ for i in thermal_gens @show get_name(i) end ``` -To update the names we will use the [`set_name`](@ref) function. However, it is important to note that using [`set_name`](@ref) not only changes the field `name`, but also changes the container itself. Therefore, it is crucial to do the following: +To update the names we will use the [set_name!](@ref) function. However, it is important to note that using [set_name!](@ref) not only changes the field `name`, but also changes the container itself. Therefore, it is crucial to do the following: ```@repl system for thermal_gen in collect(get_components(ThermalStandard, sys)) set_name!(sys, thermal_gen, get_name(thermal_gen)*"-renamed") From 5622382f1fb96ecb983ab28ed05cc6cc1bf0dc10 Mon Sep 17 00:00:00 2001 From: annacasavant Date: Mon, 25 Nov 2024 11:44:27 -0700 Subject: [PATCH 6/6] needed to get rid of the "@ref" --- docs/src/tutorials/manipulating_datasets.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/src/tutorials/manipulating_datasets.md b/docs/src/tutorials/manipulating_datasets.md index c0baff0868..da17876f02 100644 --- a/docs/src/tutorials/manipulating_datasets.md +++ b/docs/src/tutorials/manipulating_datasets.md @@ -178,7 +178,7 @@ show_components(ThermalStandard, sys) Recall that the default columns returned when using [`show_components`](@ref) are the name and availability. ## Getting Buses -We can access the [`ACBus]`(@ref), notice that we need define some basic data, including the bus's +We can access the [`ACBus`](@ref), notice that we need define some basic data, including the bus's components in the system using the [`get_buses`](@ref) function. There are multiple approaches to using this function, but in this tutorial we are going to focus on getting buses using the ID numbers. Let's begin by accessing the ID numbers associated with the [`ACBus`](@ref), notice that we need define some basic data, including the bus's components using the [`get_bus_numbers`](@ref) function. @@ -215,4 +215,4 @@ get_name.(get_components(ThermalStandard,sys)) ## Next Steps & Links So far we have seen that we can view different data types in our system using the `show_components` function, we can access those types using the `get_*` function, and we can manipulate them using the `set_*` functions. -Follow the next tutorials to learn how to [work with time series](https://nrel-sienna.github.io/PowerSystems.jl/stable/tutorials/working_with_time_series/). \ No newline at end of file +Follow the next tutorials to learn how to [work with time series](https://nrel-sienna.github.io/PowerSystems.jl/stable/tutorials/working_with_time_series/). \ No newline at end of file