Skip to content

Commit 5bc7404

Browse files
lukelowrylukelowry
committed
distill documentaiton
1 parent fe85267 commit 5bc7404

33 files changed

Lines changed: 171 additions & 457 deletions

‎GridKit/AutomaticDifferentiation/Enzyme/D2LDx2.hpp‎

Lines changed: 4 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -19,14 +19,10 @@ namespace GridKit
1919
namespace Sparse
2020
{
2121
/**
22-
* @brief Enzyme automatic differentiation Hessian evaluator: Lagrangian Hessian, d2L/dx2
22+
* @brief Enzyme sparse Hessian of \f$L = \sigma f + \lambda^T g\f$, by one
23+
* forward sweep per local variable over the reverse gradient of \f$L\f$
2324
*
24-
* Hessian of \f$L = \sigma f(x) + \lambda^T g(x)\f$ by one forward sweep
25-
* per local variable over the reverse-mode gradient of \f$L\f$. Only
26-
* structural entries are stored, in global indices.
27-
*
28-
* @tparam ModelT - model type with internal and external local variables
29-
* and constraints
25+
* @tparam ModelT - optimization component model
3026
*/
3127
template <typename ModelT>
3228
struct D2LDx2
@@ -110,11 +106,7 @@ namespace GridKit
110106
return value;
111107
}
112108

113-
/**
114-
* @brief Add the gradient of the Lagrangian to `gradient`
115-
*
116-
* Only the tangent of `gradient` is used, so it is not reset.
117-
*/
109+
/// Add the Lagrangian gradient to `gradient`, whose tangent alone is used
118110
template <typename ScalarT, typename RealT>
119111
[[gnu::always_inline]] inline static void lagrangianGradient(const ModelT* model,
120112
const ScalarT* x,

‎GridKit/AutomaticDifferentiation/Enzyme/DfDx.hpp‎

Lines changed: 2 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -18,11 +18,9 @@ namespace GridKit
1818
namespace Sparse
1919
{
2020
/**
21-
* @brief Enzyme automatic differentiation gradient evaluator: objective gradient, df/dx
21+
* @brief Enzyme objective gradient, df/dx, by one reverse sweep
2222
*
23-
* One reverse sweep.
24-
*
25-
* @tparam ModelT - model type with internal and external local variables
23+
* @tparam ModelT - optimization component model
2624
*/
2725
template <typename ModelT>
2826
struct DfDx

‎GridKit/AutomaticDifferentiation/Enzyme/DgDx.hpp‎

Lines changed: 3 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -19,13 +19,10 @@ namespace GridKit
1919
namespace Sparse
2020
{
2121
/**
22-
* @brief Enzyme automatic differentiation Jacobian evaluator: constraint Jacobian, dg/dx
22+
* @brief Enzyme sparse constraint Jacobian, dg/dx, by one forward sweep
23+
* per local variable
2324
*
24-
* One forward sweep per local variable. Only structural entries are
25-
* stored, in global indices.
26-
*
27-
* @tparam ModelT - model type with internal and external local variables
28-
* and constraints
25+
* @tparam ModelT - optimization component model
2926
*/
3027
template <typename ModelT>
3128
struct DgDx

‎GridKit/AutomaticDifferentiation/Enzyme/ModelWrappers.hpp‎

Lines changed: 0 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -233,8 +233,6 @@ namespace GridKit
233233

234234
/**
235235
* @brief Wrapper partial template specialization for an optimization objective
236-
*
237-
* Local variables are the internal variables, then the external ones.
238236
*/
239237
template <typename ModelT>
240238
struct ModelWrapper<ModelT, MemberFunctions::Objective>
@@ -259,8 +257,6 @@ namespace GridKit
259257

260258
/**
261259
* @brief Wrapper partial template specialization for optimization constraints
262-
*
263-
* Local contributions are those to the internal constraints, then those at the ports.
264260
*/
265261
template <typename ModelT>
266262
struct ModelWrapper<ModelT, MemberFunctions::Constraints>

‎GridKit/Model/OptimalPowerFlow/Branch/Branch.hpp‎

Lines changed: 1 addition & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -41,11 +41,7 @@ namespace GridKit
4141
DQ2, ///< \f$\Delta Q_2^\mathrm{bus}\f$ Reactive power into bus 2 [p.u.]
4242
};
4343

44-
/**
45-
* @brief Line or off-nominal transformer between two buses
46-
*
47-
* Power is positive into the buses.
48-
*/
44+
/// Line or off-nominal transformer between two buses, with power positive into the buses
4945
template <typename scalar_type, typename index_type>
5046
class Branch final : public Component<scalar_type, index_type>
5147
{

‎GridKit/Model/OptimalPowerFlow/Branch/BranchData.hpp‎

Lines changed: 1 addition & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -35,12 +35,7 @@ namespace GridKit
3535
bus2, ///< Bus-2 port
3636
};
3737

38-
/**
39-
* @brief Contains modeling data for a Branch
40-
*
41-
* @tparam real_type Real parameter data type
42-
* @tparam index_type Integer data type
43-
*/
38+
/// Data of a `Branch`
4439
template <typename real_type, typename index_type>
4540
using BranchData = ComponentData<real_type, index_type, BranchParameters, BranchPorts>;
4641
} // namespace OptimalPowerFlow

‎GridKit/Model/OptimalPowerFlow/Branch/BranchImpl.hpp‎

Lines changed: 2 additions & 22 deletions
Original file line numberDiff line numberDiff line change
@@ -34,9 +34,6 @@ namespace GridKit
3434
return checks;
3535
}
3636

37-
/**
38-
* @brief The squared apparent power at each port is an inequality
39-
*/
4037
template <typename scalar_type, typename index_type>
4138
int Branch<scalar_type, index_type>::tagInequality()
4239
{
@@ -48,9 +45,6 @@ namespace GridKit
4845
return 0;
4946
}
5047

51-
/**
52-
* @brief The rating bounds the squared apparent power at each port
53-
*/
5448
template <typename scalar_type, typename index_type>
5549
int Branch<scalar_type, index_type>::initialize()
5650
{
@@ -64,9 +58,6 @@ namespace GridKit
6458
return 0;
6559
}
6660

67-
/**
68-
* @brief Squared apparent power at bus 1 and at bus 2
69-
*/
7061
template <typename scalar_type, typename index_type>
7162
[[gnu::always_inline]] void
7263
Branch<scalar_type, index_type>::internalConstraints([[maybe_unused]] const ScalarT* x,
@@ -87,10 +78,6 @@ namespace GridKit
8778
g[S2] = s[DP2] * s[DP2] + s[DQ2] * s[DQ2];
8879
}
8980

90-
/**
91-
* @brief Active and reactive power into bus 1, then into bus 2, added to
92-
* their balances
93-
*/
9481
template <typename scalar_type, typename index_type>
9582
[[gnu::always_inline]] void
9683
Branch<scalar_type, index_type>::externalConstraints([[maybe_unused]] const ScalarT* x,
@@ -120,10 +107,7 @@ namespace GridKit
120107
setDerivedParameters();
121108
}
122109

123-
/**
124-
* @brief Pi-model admittance with the off-nominal tap and phase shift on
125-
* the bus-1 side, zero out of service
126-
*/
110+
/// Pi-model admittance with the tap and phase shift on the bus-1 side, zero out of service
127111
template <typename scalar_type, typename index_type>
128112
void Branch<scalar_type, index_type>::setDerivedParameters()
129113
{
@@ -150,11 +134,7 @@ namespace GridKit
150134
b22_ = u * (-b_br - HALF<RealT> * B_);
151135
}
152136

153-
/**
154-
* @brief Active and reactive power into bus 1, then into bus 2
155-
*
156-
* The power into each bus is \f$P + jQ = V I^*\f$.
157-
*/
137+
/// Power \f$P + jQ = V I^*\f$ into bus 1, then into bus 2
158138
template <typename scalar_type, typename index_type>
159139
[[gnu::always_inline]] void
160140
Branch<scalar_type, index_type>::power(const ScalarT* external, ScalarT* s) const

‎GridKit/Model/OptimalPowerFlow/Branch/README.md‎

Lines changed: 1 addition & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -15,11 +15,10 @@ $B_\mathrm{mag}$ | [p.u.] | `Bmag` | Magnetizing shunt susceptance at bus
1515
$\tau$ | [p.u.] | `tap` | Off-nominal tap magnitude on the bus-1 side | | Default 1
1616
$\theta$ | [rad] | `phase` | Phase-shift angle | | Default 0
1717
$S^{\max}$ | [p.u.] | `Smax` | Apparent power limit at each port | | Default unbounded
18-
$u$ | [-] | `in_service` | Service status, 1 in service and 0 out of service | | Default true
18+
$u$ | [-] | `in_service` | Service status | | Default true
1919

2020
### Parameter Validation
2121

22-
- $R$, $X$, $G$, $B$, $G_\mathrm{mag}$, $B_\mathrm{mag}$, $\tau$, and $\theta$ are finite
2322
- $R^2 + X^2 > 0$
2423
- $\tau > 0$
2524
- $S^{\max} > 0$

‎GridKit/Model/OptimalPowerFlow/Bus/Bus.hpp‎

Lines changed: 2 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -15,14 +15,14 @@ namespace GridKit
1515
{
1616
namespace OptimalPowerFlow
1717
{
18-
/// Internal variables of a `Bus`, its voltage, which a port reads
18+
/// Internal variables of a `Bus`
1919
enum class BusInternalVariables : size_t
2020
{
2121
VR, ///< \f$V_\mathrm{r}\f$ Real voltage [p.u.]
2222
VI, ///< \f$V_\mathrm{i}\f$ Imaginary voltage [p.u.]
2323
};
2424

25-
/// Internal constraints of a `Bus`, its power balance first, which a port contributes to
25+
/// Internal constraints of a `Bus`, its power balance first
2626
enum class BusInternalConstraints : size_t
2727
{
2828
P, ///< Active power balance [p.u.]
@@ -33,10 +33,6 @@ namespace GridKit
3333
/**
3434
* @brief Bus voltage in Cartesian coordinates, power balance, and shunt
3535
* admittance to ground
36-
*
37-
* A port to the bus reads its voltage and contributes to its power
38-
* balance. Each balance equality is the power into the bus from its shunt
39-
* and from its ports.
4036
*/
4137
template <typename scalar_type, typename index_type>
4238
class Bus final : public Component<scalar_type, index_type>

‎GridKit/Model/OptimalPowerFlow/Bus/BusData.hpp‎

Lines changed: 1 addition & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -25,12 +25,7 @@ namespace GridKit
2525
reference, ///< Angle reference, with zero imaginary voltage
2626
};
2727

28-
/**
29-
* @brief Contains modeling data for a Bus
30-
*
31-
* @tparam real_type Real parameter data type
32-
* @tparam index_type Integer data type
33-
*/
28+
/// Data of a `Bus`, identified by its number
3429
template <typename real_type, typename index_type>
3530
struct BusData
3631
{
@@ -41,7 +36,6 @@ namespace GridKit
4136
/// Bus number
4237
IdxT number{0};
4338

44-
/// Mapping of parameters to parameter values
4539
ParameterMap<Parameters, RealT, IdxT> parameters;
4640

4741
/// Bus `id`, from its number

0 commit comments

Comments
 (0)