From 72a01607e43d0b34e0dde8a0ba9058a29dc103fb Mon Sep 17 00:00:00 2001 From: Ray Zimmerman Date: Wed, 21 Feb 2024 11:38:57 -0700 Subject: [PATCH] Clean up :attr: and :meth: references in documentation. --- .../sphinx/source/dev-manual/architecture.rst | 2 +- .../dev-manual/data-model-converter.rst | 2 +- docs/sphinx/source/dev-manual/data-model.rst | 36 +++++++++---------- docs/sphinx/source/dev-manual/math-model.rst | 4 +-- docs/sphinx/source/dev-manual/net-model.rst | 4 +-- docs/sphinx/source/howto/element.rst | 22 ++++++------ .../source/howto/gizmo-element/index.rst | 4 +-- lib/+mp/net_model.m | 2 +- lib/+mp/nm_element.m | 2 +- 9 files changed, 39 insertions(+), 39 deletions(-) diff --git a/docs/sphinx/source/dev-manual/architecture.rst b/docs/sphinx/source/dev-manual/architecture.rst index 455de877..2d003f2d 100644 --- a/docs/sphinx/source/dev-manual/architecture.rst +++ b/docs/sphinx/source/dev-manual/architecture.rst @@ -90,7 +90,7 @@ A summary of the class inheritance structure in MP-Core is represented in :numre Subclasses in these hierarchies are distinguished from one another by various attributes. For example, task classes are distinguished by the type of *task* or problem being solved (e.g. PF, CPF, OPF), data model converters by the *data format* (e.g. |MATPOWER| case v2, PSS/E RAW), data models by the *task*, network models by the *formulation* (e.g. DC, AC polar, AC cartesian), mathematical models by the *task* and *formulation*. That goes for both the container classes and their respective element classes, which are also distinguished by the corresponding *element type* (e.g. bus, generator, transmission line). -The :class:`mp.element_container` is a mixin class providing shared functionality for the four container types mentioned above, implementing a set of elements, which can be addressed by both index and name and supplying the properties :attr:`elements` and :attr:`element_classes`. +The :class:`mp.element_container` is a mixin class providing shared functionality for the four container types mentioned above, implementing a set of elements, which can be addressed by both index and name and supplying the properties :attr:`elements ` and :attr:`element_classes `. Other mixin classes are also sometimes used when certain functionality and implementation is shared across classes in ways that do not match the primary inheritance paths. diff --git a/docs/sphinx/source/dev-manual/data-model-converter.rst b/docs/sphinx/source/dev-manual/data-model-converter.rst index 18d77b97..3e102910 100644 --- a/docs/sphinx/source/dev-manual/data-model-converter.rst +++ b/docs/sphinx/source/dev-manual/data-model-converter.rst @@ -23,7 +23,7 @@ By convention, data model converter variables are named ``dmc`` and data model c Building a Data Model Converter ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -A data model converter object is created in two steps. The first is to call the constructor of the desired data model converter class, without arguments. This initializes the :attr:`element_classes` property with a list of data model converter element classes. This list can be modified before the second step, which is to call the :meth:`build() ` method, also without parameters, which simply instantiates and adds the set of element objects indicated in :attr:`element_classes`. Once it has been created, it is ready to be used for its two primary functions, namely *import* and *export*. +A data model converter object is created in two steps. The first is to call the constructor of the desired data model converter class, without arguments. This initializes the :attr:`element_classes ` property with a list of data model converter element classes. This list can be modified before the second step, which is to call the :meth:`build() ` method, also without parameters, which simply instantiates and adds the set of element objects indicated in :attr:`element_classes `. Once it has been created, it is ready to be used for its two primary functions, namely *import* and *export*. .. _code_data_model_build: .. code-block:: diff --git a/docs/sphinx/source/dev-manual/data-model.rst b/docs/sphinx/source/dev-manual/data-model.rst index c89fb31d..b75d7130 100644 --- a/docs/sphinx/source/dev-manual/data-model.rst +++ b/docs/sphinx/source/dev-manual/data-model.rst @@ -27,7 +27,7 @@ By convention, data model variables are named ``dm`` and data model class names Building a Data Model ^^^^^^^^^^^^^^^^^^^^^ -There are two steps to building a data model. The first is to call the constructor of the desired data model class, without arguments. This initializes the :attr:`element_classes` property with a list of data model element classes. This list can be modified before the second step, which is to call the :meth:`build() ` method, passing in the data and a corresponding data model converter object. +There are two steps to building a data model. The first is to call the constructor of the desired data model class, without arguments. This initializes the :attr:`element_classes ` property with a list of data model element classes. This list can be modified before the second step, which is to call the :meth:`build() ` method, passing in the data and a corresponding data model converter object. .. _code_data_model_build: .. code-block:: @@ -38,18 +38,18 @@ There are two steps to building a data model. The first is to call the construct The :meth:`build() ` method proceeds through the following stages sequentially, looping through each element at every stage. - 1. **Create** – Instantiate each element object and add it to the :attr:`elements` property of the ``dm``. + 1. **Create** – Instantiate each element object and add it to the :attr:`elements ` property of the ``dm``. 2. **Import** – Use the corresponding data model converter element to read the data into each element's table(s). - 3. **Count** – Determine the number of instances of each element present in the data, store it in the element's :attr:`nr` property, and remove the element type from :attr:`elements` if the count is 0. - 4. **Initialize** – Initialize the (online/offline) status of each element and create a mapping of ID to row index in the :attr:`ID2i` element property. - 5. **Update status** – Update status of each element based on connectivity or other criteria and define element properties containing number and row indices of online elements (:attr:`n` and :attr:`on`), indices of offline elements (:attr:`off`), and mapping (:attr:`i2on`) of row indices to corresponding entries in :attr:`on` or :attr:`off`. + 3. **Count** – Determine the number of instances of each element present in the data, store it in the element's :attr:`nr ` property, and remove the element type from :attr:`elements ` if the count is 0. + 4. **Initialize** – Initialize the (online/offline) status of each element and create a mapping of ID to row index in the :attr:`ID2i ` element property. + 5. **Update status** – Update status of each element based on connectivity or other criteria and define element properties containing number and row indices of online elements (:attr:`n ` and :attr:`on `), indices of offline elements (:attr:`off `), and mapping (:attr:`i2on `) of row indices to corresponding entries in :attr:`on ` or :attr:`off `. 6. **Build parameters** – Extract/convert/calculate parameters as necessary for online elements from the original data tables (e.g. p.u. conversion, initial state, etc.) and store them in element-specific properties. System Level Parameters ^^^^^^^^^^^^^^^^^^^^^^^ -There are a few system level parameters such as the system per-unit power base that are stored in data model properties. Balanced single-phase model elements, typical in transmission systems, use an MVA base found in :attr:`base_mva`. Unbalanced three-phase model elements, typical in distribution systems, use a kVA base found in :attr:`base_kva`. Models with both types of elements, therefore, use both properties. +There are a few system level parameters such as the system per-unit power base that are stored in data model properties. Balanced single-phase model elements, typical in transmission systems, use an MVA base found in :attr:`base_mva `. Unbalanced three-phase model elements, typical in distribution systems, use a kVA base found in :attr:`base_kva `. Models with both types of elements, therefore, use both properties. Printing a Data Model @@ -85,7 +85,7 @@ By convention, data model element variables are named ``dme`` and data model ele Data Tables ^^^^^^^^^^^ -Typically, a data model element has at least one main table, stored in the :attr:`tab` property. Each row in the table corresponds to an individual element and the columns are the parameters. In general, |MATPOWER| attempts to follow the parameter naming conventions outlined in *The Common Electric Power Transmission System Model* (CTM) [CTM]_. The following parameters (table columns) are shared by all data model elements. +Typically, a data model element has at least one main table, stored in the :attr:`tab ` property. Each row in the table corresponds to an individual element and the columns are the parameters. In general, |MATPOWER| attempts to follow the parameter naming conventions outlined in *The Common Electric Power Transmission System Model* (CTM) [CTM]_. The following parameters (table columns) are shared by all data model elements. - **uid** – positive integer serving as a unique identifier for the element - **name** – optional string identifier for the element @@ -95,7 +95,7 @@ Typically, a data model element has at least one main table, stored in the :attr Properties ^^^^^^^^^^ -The table below includes additional properties, besides the main table :attr:`tab`, found in all data model elements. +The table below includes additional properties, besides the main table :attr:`tab `, found in all data model elements. .. _tab_dme_properties: .. list-table:: Data Model Element Properties @@ -105,20 +105,20 @@ The table below includes additional properties, besides the main table :attr:`ta * - Property - Description - * - :attr:`nr` + * - :attr:`nr ` - number of rows in the table, i.e. the *total* number of elements of the type - * - :attr:`n` + * - :attr:`n ` - number of *online* elements of the type - * - :attr:`on` + * - :attr:`on ` - vector of row indices of online elements - * - :attr:`off` + * - :attr:`off ` - vector of row indices of offline elements - * - :attr:`ID2i` + * - :attr:`ID2i ` - :math:`M \times 1` vector mapping IDs to row indices, where :math:`M` is the largest ID value - * - :attr:`i2on` - - :math:`n_r \times 1` vector mapping row indices to the corresponding index into the :attr:`on` - vector *(for online elements)* or :attr:`off` vector *(for offline elements)* - * - :attr:`tab` + * - :attr:`i2on ` + - :math:`n_r \times 1` vector mapping row indices to the corresponding index into the :attr:`on ` + vector *(for online elements)* or :attr:`off ` vector *(for offline elements)* + * - :attr:`tab ` - main data table Methods @@ -146,7 +146,7 @@ As described in the :ref:`sec_net_model` section, the network model consists of A **connection** in this context refers to a mapping of a set of ports of an element of type *A* (e.g. *from bus* and *to bus* ports of a *branch*) to a set of nodes created by elements of type *B* (e.g. *bus*). We call the node-creating elements **junction** elements. A single connection links all type *A* elements to corresponding type *B* junction elements. For example, a three-phase branch could define two connections, a *from bus* connection and a *to bus* connection, where each connection defines a mapping of 3 ports per branch to the 3 nodes of each corresponding bus. -A data model element class defines its connections by implementing a couple of methods. The :meth:`cxn_type() ` method returns the name of the junction element(s) for the connection(s). The :meth:`cxn_idx_prop() ` method returns the name(s) of the property(ies) containing the indices of the corresponding junction elements. For example, if :meth:`cxn_type() ` for a branch element class returns ``'bus'`` and :meth:`cxn_idx_prop() ` returns ``{'fbus', 'tbus'}``, that means it is defining two connections, both to ``'bus'`` elements. The :attr:`fbus` and :attr:`tbus` properties of the branch object are each vectors of indices into the set of ``'bus'`` objects, and will be used automatically to generate the connectivity for the network model. +A data model element class defines its connections by implementing a couple of methods. The :meth:`cxn_type() ` method returns the name of the junction element(s) for the connection(s). The :meth:`cxn_idx_prop() ` method returns the name(s) of the property(ies) containing the indices of the corresponding junction elements. For example, if :meth:`cxn_type() ` for a branch element class returns ``'bus'`` and :meth:`cxn_idx_prop() ` returns ``{'fbus', 'tbus'}``, that means it is defining two connections, both to ``'bus'`` elements. The :attr:`fbus ` and :attr:`tbus ` properties of the branch object are each vectors of indices into the set of ``'bus'`` objects, and will be used automatically to generate the connectivity for the network model. It is also possible to define a connection where the junction element type is instance-specific. For example, if you had two types of buses, and a load element that could connect to either type, then each load would have to indicate both which type of bus and which bus of that type it is connected to. This is done by having :meth:`cxn_type() ` return a cell array of the valid junction element type sand :meth:`cxn_type_prop() ` return the name(s) of the property(ies) containing vector(s) of indices into the junction element type cell array. diff --git a/docs/sphinx/source/dev-manual/math-model.rst b/docs/sphinx/source/dev-manual/math-model.rst index 17fbeec5..0c58867e 100644 --- a/docs/sphinx/source/dev-manual/math-model.rst +++ b/docs/sphinx/source/dev-manual/math-model.rst @@ -67,7 +67,7 @@ By convention, math model variables are named ``mm`` and math model class names Building a Mathematical Model ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -A math model object is created in two steps. The first is to call the constructor of the desired math model class, without arguments. This initializes the :attr:`element_classes` property with a list of math model element classes. This list can be modified before the second step, which is to call the :meth:`build() ` method, passing in the network and data model objects and a |MATPOWER| options struct. +A math model object is created in two steps. The first is to call the constructor of the desired math model class, without arguments. This initializes the :attr:`element_classes ` property with a list of math model element classes. This list can be modified before the second step, which is to call the :meth:`build() ` method, passing in the network and data model objects and a |MATPOWER| options struct. .. _code_math_model_build: .. code-block:: @@ -78,7 +78,7 @@ A math model object is created in two steps. The first is to call the constructo The :meth:`build() ` method proceeds through the following stages sequentially, looping through each element for the last 3 stages. 1. **Create** – Instantiate each element object. - 2. **Count and add** - For each element object, determine the number of online elements from the corresponding data model element and, if nonzero, add the object to the :attr:`elements` property of the ``mm``. + 2. **Count and add** - For each element object, determine the number of online elements from the corresponding data model element and, if nonzero, add the object to the :attr:`elements ` property of the ``mm``. 3. **Add auxiliary data** – Add auxiliary data, e.g. network node types, for use by the model. 4. **Add variables** – Add variables and allow each element to add their own variables to the model. 5. **Add constraints** – Add constraints and allow each element to add their own constraints to the model. diff --git a/docs/sphinx/source/dev-manual/net-model.rst b/docs/sphinx/source/dev-manual/net-model.rst index 3d888107..ee33587e 100644 --- a/docs/sphinx/source/dev-manual/net-model.rst +++ b/docs/sphinx/source/dev-manual/net-model.rst @@ -166,7 +166,7 @@ By convention, network model variables are named ``nm`` and network model class Building a Network Model ^^^^^^^^^^^^^^^^^^^^^^^^ -A network model object is created in two steps. The first is to call the constructor of the desired network model class, without arguments. This initializes the :attr:`element_classes` property with a list of network model element classes. This list can be modified before the second step, which is to call the :meth:`build() ` method, passing in the data model object. +A network model object is created in two steps. The first is to call the constructor of the desired network model class, without arguments. This initializes the :attr:`element_classes ` property with a list of network model element classes. This list can be modified before the second step, which is to call the :meth:`build() ` method, passing in the data model object. .. _code_net_model_build: .. code-block:: @@ -177,7 +177,7 @@ A network model object is created in two steps. The first is to call the constru The :meth:`build() ` method proceeds through the following stages sequentially, looping through each element at each stage. 1. **Create** – Instantiate each element object. - 2. **Count and add** - For each element object, determine the number of online elements from the corresponding data model element and, if nonzero, store it in the object and add the object to the :attr:`elements` property of the ``nm``. + 2. **Count and add** - For each element object, determine the number of online elements from the corresponding data model element and, if nonzero, store it in the object and add the object to the :attr:`elements ` property of the ``nm``. 3. **Add nodes** – Allow each element to add network nodes, then add voltage variables for each node. 4. **Add states** – Allow each element to add non-voltage states, then add non-voltage variables for each state. 5. **Build parameters** – Construct the formulation-specific model parameters for each element, including mappings of element port to network node and element non-voltage state to system non-voltage variable. Add ports to the container object for each element to track per-element port indexing. diff --git a/docs/sphinx/source/howto/element.rst b/docs/sphinx/source/howto/element.rst index 4d6eb008..1bdc8e37 100644 --- a/docs/sphinx/source/howto/element.rst +++ b/docs/sphinx/source/howto/element.rst @@ -137,13 +137,13 @@ This data is stored in the main data table in the :attr:`tab end %% methods end %% classdef -For element types that connect to one or more buses, it is typical to define a property for each port in the data model element class. In our case, there are two properties, :attr:`fbus` and :attr:`tbus`, which will hold bus index vectors for ports 1 and 2, respectively. That is ``dme.tbus(k)`` will refer to the index of the bus connected to port 2, the *to* bus, of the DC line defined in row *k* of the data table. +For element types that connect to one or more buses, it is typical to define a property for each port in the data model element class. In our case, there are two properties, :attr:`fbus ` and :attr:`tbus `, which will hold bus index vectors for ports 1 and 2, respectively. That is ``dme.tbus(k)`` will refer to the index of the bus connected to port 2, the *to* bus, of the DC line defined in row *k* of the data table. .. note:: - The contents of :attr:`fbus` and :attr:`tbus` are not bus IDs, that is external bus numbers, but rather internal indices of the corresponding buses, that is, row indices into ``dm.elements.bus.tab``, the table of all buses in the bus data model element object. + The contents of :attr:`fbus ` and :attr:`tbus ` are not bus IDs, that is external bus numbers, but rather internal indices of the corresponding buses, that is, row indices into ``dm.elements.bus.tab``, the table of all buses in the bus data model element object. -The :attr:`fbus_on` and :attr:`tbus_on` properties, on the other, hand map in-service DC lines to the in-service buses. That is ``dme.fbus_on(k)`` is the index into the list of in-service buses for the bus connected to port 1, the *from* bus, of the *k*-th in-service DC line. +The :attr:`fbus_on ` and :attr:`tbus_on ` properties, on the other, hand map in-service DC lines to the in-service buses. That is ``dme.fbus_on(k)`` is the index into the list of in-service buses for the bus connected to port 1, the *from* bus, of the *k*-th in-service DC line. The other properties correspond to the respective columns in the data table, but after removing DC lines that are out-of-service and, in some cases, converting to per unit. Those that end in ``_start`` are for the initial value of the respective variable. @@ -171,7 +171,7 @@ The :meth:`name() ` method returns ``'legacy_dcline'``, the Connectivity ^^^^^^^^^^^^ -The :meth:`cxn_type() ` and :meth:`cxn_idx_prop() ` methods specify that ``'legacy_dcline'`` objects connect to ``'bus'`` objects, and that the corresponding bus indices for ports 1 and 2 can be found in properties :attr:`fbus` and :attr:`tbus`, respectively. +The :meth:`cxn_type() ` and :meth:`cxn_idx_prop() ` methods specify that ``'legacy_dcline'`` objects connect to ``'bus'`` objects, and that the corresponding bus indices for ports 1 and 2 can be found in properties :attr:`fbus ` and :attr:`tbus `, respectively. .. _code_dme_legacy_dcline_cxn: .. code-block:: @@ -231,7 +231,7 @@ Building the Element in Stages When a data model object and its elements are created, they are built in the stages described in :ref:`sec_building_data_model` in the |MATPOWER-Dev-Manual|. -The :meth:`initialize() ` method is called during the **initialize** stage. It takes advantage of the bus ID-to-index mapping available from the ``'bus'`` data model element object to populate the :attr:`fbus` and :attr:`tbus` properties from the corresponding columns in the main data table. +The :meth:`initialize() ` method is called during the **initialize** stage. It takes advantage of the bus ID-to-index mapping available from the ``'bus'`` data model element object to populate the :attr:`fbus ` and :attr:`tbus ` properties from the corresponding columns in the main data table. .. _code_dme_legacy_dcline_initialize: .. code-block:: @@ -247,7 +247,7 @@ The :meth:`initialize() ` method is called during the obj.tbus = b2i(obj.tab.bus_to); end -The :meth:`update_status() ` method, called during the **update status** stage, updates the default online/offline status, which has already been initialized from the ``status`` column of the main data table, to remove from service any DC line that is connected to an offline bus. After calling the parent method to populate the :attr:`on` and :attr:`off` properties, this method also updates some data in the bus data model element object to set the bus type for DC terminal buses to PV and turn on their voltage-controlled flag. +The :meth:`update_status() ` method, called during the **update status** stage, updates the default online/offline status, which has already been initialized from the ``status`` column of the main data table, to remove from service any DC line that is connected to an offline bus. After calling the parent method to populate the :attr:`on ` and :attr:`off ` properties, this method also updates some data in the bus data model element object to set the bus type for DC terminal buses to PV and turn on their voltage-controlled flag. .. _code_dme_legacy_dcline_update_status: .. code-block:: @@ -421,7 +421,7 @@ While we could have put the limit parameters themselves in the OPF subclass, sin The other addition in the OPF subclass is an optional cost on the active power flow in the DC line. This cost is specified in the same way as a generator cost, either as a set of polynomial coefficients, or as a set of breakpoints in a piecewise linear function. It appears as a column in the main table and is of type :class:`mp.cost_table`. -There is also a :meth:`have_cost` method that returns true for OPF subclass and false in the base class. It is used by the export routines of the data model converter element to determine whether or not to export cost data. +There is also a :meth:`have_cost() ` method that returns true for OPF subclass and false in the base class. It is used by the export routines of the data model converter element to determine whether or not to export cost data. .. _code_dme_legacy_dcline_opf_have_cost: .. code-block:: @@ -430,7 +430,7 @@ There is also a :meth:`have_cost` method that returns true for OPF subclass and TorF = 1; end -The :meth:`build_cost_params` method is called during the creation of an OPF mathematical model to extract the costs from the data and put it in a form more convenient for adding to the math model. The implementation is built on the same :class:`mp.cost_table` and :class:`mp.cost_table_utils` classes used for generator costs. +The :meth:`build_cost_params() ` method is called during the creation of an OPF mathematical model to extract the costs from the data and put it in a form more convenient for adding to the math model. The implementation is built on the same :class:`mp.cost_table` and :class:`mp.cost_table_utils` classes used for generator costs. .. _code_dme_legacy_dcline_opf_build_cost_params: .. code-block:: @@ -449,7 +449,7 @@ The :meth:`build_cost_params` method is called during the creation of an OPF mat end end -Finally, there are several methods for handling the pretty-printing of the limits (**lim**) section, which is only relevant for the OPF. The :meth:`pretty_print() ` method is overridden to set up some data for limit sections, namely flows and shadow prices, to be passed via ``pp_args`` to the methods that do the printing. +Finally, there are several methods for handling the pretty-printing of the limits (**lim**) section, which is only relevant for the OPF. The :meth:`pretty_print() ` method is overridden to set up some data for limit sections, namely flows and shadow prices, to be passed via ``pp_args`` to the methods that do the printing. .. _code_dme_legacy_dcline_opf_pretty_print: .. code-block:: @@ -926,7 +926,7 @@ For the OPF, there are a number of additions, including the constraint on the "f end %% methods end %% classdef -This class adds a :attr:`cost` property which holds the necessary cost data in a form that is convenient for constructing the math model costs. This field is populated by the :meth:`build_cost_params` method by calling a method of the same name in the corresponding data model element. +This class adds a :attr:`cost ` property which holds the necessary cost data in a form that is convenient for constructing the math model costs. This field is populated by the :meth:`build_cost_params() ` method by calling a method of the same name in the corresponding data model element. .. _code_mme_legacy_dcline_opf_build_cost_params: @@ -1121,7 +1121,7 @@ The complete source for the DC line mathematical model element classes above can Using the New Element --------------------- -Now that each of the element classes for the DC line have been implemented for each of the model layers and the data model converter, these classes need to be included when running a power flow, continuation power flow, or optimal power flow. If this implementation for DC lines were to be added to the set of standard elements, along side of buses, branches, and generators, for example, then the classes would be added to the lists assigned to the :attr:`element_classes` property in the constructor of the appropriate model container class. E.g. :class:`mp.nme_legacy_dcline_dc` in :class:`mp.net_model_dc`, and :class:`mp.mme_legacy_opf_dcline_ac` in :class:`mp.math_model_opf_acc` and :class:`mp.math_model_opf_acp`. +Now that each of the element classes for the DC line have been implemented for each of the model layers and the data model converter, these classes need to be included when running a power flow, continuation power flow, or optimal power flow. If this implementation for DC lines were to be added to the set of standard elements, along side of buses, branches, and generators, for example, then the classes would be added to the lists assigned to the :attr:`element_classes ` property in the constructor of the appropriate model container class. E.g. :class:`mp.nme_legacy_dcline_dc` in :class:`mp.net_model_dc`, and :class:`mp.mme_legacy_opf_dcline_ac` in :class:`mp.math_model_opf_acc` and :class:`mp.math_model_opf_acp`. However, for user additions that are not being contributed for inclusion in the standard |MATPOWER| distribution, the original |MATPOWER| source need not, and should not, be modified. Instead, we use the |MATPOWER| Extension API. diff --git a/docs/sphinx/source/howto/gizmo-element/index.rst b/docs/sphinx/source/howto/gizmo-element/index.rst index 7ffd9657..bee479f2 100644 --- a/docs/sphinx/source/howto/gizmo-element/index.rst +++ b/docs/sphinx/source/howto/gizmo-element/index.rst @@ -57,7 +57,7 @@ Data Model Element We begin with the data model element for a **gizmo**. The data for each gizmo consists of the three buses to which its ports are connected, values of the two non-voltage states, and the 8 parameters shown in :numref:`fig_gizmo_model` and :numref:`tab_gizmo_components` above. For the complex values, we specify the real and imaginary parts as separate parameters. -This data is stored in the main data table in the :attr:`tab` property of the data model element object of type :class:`mp.dme_gizmo`. This is a MATLAB |table|_ object, or an :class:`mp_table` object if running in Octave. The names of the columns in :attr:`tab` are shown in :numref:`tab_gizmo_data_model` below. Each row in :attr:`tab` corresponds to an individual gizmo, which means there is a single instance of a gizmo data model element object to hold the data for all gizmos in the system. +This data is stored in the main data table in the :attr:`tab ` property of the data model element object of type :class:`mp.dme_gizmo`. This is a MATLAB |table|_ object, or an :class:`mp_table` object if running in Octave. The names of the columns in :attr:`tab ` are shown in :numref:`tab_gizmo_data_model` below. Each row in :attr:`tab ` corresponds to an individual gizmo, which means there is a single instance of a gizmo data model element object to hold the data for all gizmos in the system. .. _tab_gizmo_data_model: .. list-table:: Gizmo Data Model @@ -167,7 +167,7 @@ The :meth:`initialize() ` method takes advantage of th Finally, :meth:`update_status() ` updates the default online/offline status, which has already been initialized from the ``status`` column of the main data table, to remove from service any gizmo that is connected to an offline bus. -Note that both :meth:`initialize() ` and :meth:`update_status() ` rely on the fact that the corresponding methods have already been called for ``'bus'`` objects before ``'gizmo'`` objects. The order corresponds to their order in :attr:`dm.element_classes` which is determined by the default defined by the data model class and any |MATPOWER| extensions or options used to modify that default. +Note that both :meth:`initialize() ` and :meth:`update_status() ` rely on the fact that the corresponding methods have already been called for ``'bus'`` objects before ``'gizmo'`` objects. The order corresponds to their order in :attr:`dm.element_classes ` which is determined by the default defined by the data model class and any |MATPOWER| extensions or options used to modify that default. The :class:`mp.dme_gizmo` class is also where you would override any of the pretty-printing methods to implement gizmo sections in your pretty-printed output. Until such methods are added to this example, you can look at the data model element classes for other element types for examples (e.g. :class:`mp.dme_bus`, :class:`mp.dme_branch`, :class:`mp.dme_gen`, :class:`mp.dme_load`, etc.) diff --git a/lib/+mp/net_model.m b/lib/+mp/net_model.m index 4fdec2c3..480fd250 100644 --- a/lib/+mp/net_model.m +++ b/lib/+mp/net_model.m @@ -351,7 +351,7 @@ % idx (integer) : index for name and indexed variables % *(currently unused here)* % - % Also updates the :attr:`nv ` property. + % Also updates the :attr:`nv` property. % % See also add_zvars, add_nodes. diff --git a/lib/+mp/nm_element.m b/lib/+mp/nm_element.m index 14b1ec3d..02c36e4a 100644 --- a/lib/+mp/nm_element.m +++ b/lib/+mp/nm_element.m @@ -427,7 +427,7 @@ % is, element *p* of ``nidxs`` is the vector of indices of the % nodes to which port *p* of these elements are connected. These % node indices can be used to construct the element-node incidence - % matrices that form :attr:`C `. + % matrices that form :attr:`C`. % % By default, the connection information is obtained from the % corresponding data model element, as described in the