Schema

These are JSON schemas for the model configuration, normalization factors, sensitivity loss configuration, clamping loss configuration, and trained model blocks. These appear in various files for a specific model:

In model_config.json, the section HWPV Model Configuration must appear. Optionally, Sensitivity Losses and Clamping Losses may appear. The user must create this file.
A training run creates normfacs.json at the beginning. The section Normalization Factors appears. The pecblocks package creates this file in a subdirectory that was specified in model_config.json.
A model export creates model_fhf.json in a subdirectory that was specified in model_config.json. The sections Block F1 or F2, Block H1, Block H1s, and Block Q1s appear. In addition, recognized sections from model_config.json and normfacs.json will be copied into model_fhf.json. The pecblocks package creates this file in the same directory as normfacs.json.

The user may add other JSON objects to model_config.json, but these are not copied into model_folder/model_fhf.json during model export.

HWPV Model Configuration

https://github.com/pnnl/pecblocks/docs/config.json
Training and evaluation parameters. This object is un-named, but it may have optional named objects clamping and sensitivity.
type	object
properties
name	Name of this model, usually PV3. Limited to 6 characters for ATP.
	type	string
type	Indicates the block structure, typically F1+H1+F2.
	type	string
t_step	Discretization time step, to match the HDF5 file.
	type	number
model_folder	Path name to the exported model files.
	type	string
model_root	Root name for the exported model JSON file.
	type	string
data_path	Path and filename to the HDF5 data.
	type	string
lr	Learning rate for the Adam optimizer in PyTorch.
	type	number
eps	Numerical stability parameter for the Adam optimizer in PyTorch.
	type	number
h5grp_prefix	Optional prefix to the case or event number in the HDF5 file, e.g., ‘case’, ‘scope’, or ‘’
	type	string
num_iter	Number of epochs to perform in the next training run.
	type	integer
	minimum	1
continue_iterations	Start with the most recently trained model coefficients rather than randomized initial model coefficients.
	type	boolean
print_freq	Number of training epochs between status messages printed to console.
	type	integer
batch_size	The batch size for more efficient training in PyTorch. Typically no larger than 10% of the number of training cases in the HDF5 file.
	type	integer
	minimum	1
n_validation_pct	Percentage of HDF5 cases to reserve for non-optimized validation in each epoch
	type	integer
	minimum	5
n_validation_seed	A number to randomize the selection of HDF5 cases reserved for validation
	type	integer
n_skip	Number of data points to ignore from the start of the HDF5 data series, before decimation. Typically 0 unless there is a long startup period for each series, as in some EMT simulators.
	type	integer
	minimum	0
n_trunc	Number of data points to ignore from the end of the HDF5 data series, before decimation. Typically 0 unless there is extraneous data at the end of each series.
	type	integer
	minimum	0
n_dec	Decimation or down-sampling interval of the HDF5 data points to the data series used for training. Specify 1 for no down-smapling.
	type	integer
	minimum	1
n_loss_skip	Number of decimated points to skip at the beginning of each data series for the fitting and validation loss evaluation. Typically 50% the value of n_pad.
	type	integer
	minimum	0
n_pad	Number of decimated points to pre-pad the training data series with initial input and output values. This helps mitigate startup transients in the H1 block. Typically 25% of the number of decimated points in the training data series.
	type	integer
	minimum	0
gtype	Linear filter form of the H1 block.
	type	string
	enum	iir, fir, stable2ndx, stable2nd
na	Number of trainable denominator coefficients in H1. Excludes a0=1. Specify 2 for the stable2nd or stable2ndx gtype.
	type	integer
	minimum	1
nb	Number of trainable numerator coefficients in H1. Specify 3 for the stable2nd or stable2ndx gtype.
	type	integer
	minimum	1
nk	Number of delay steps in the output of H1.
	type	integer
	minimum	0
activation	Nonlinear activation function in the F1 and F2 blocks.
	type	string
	enum	tanh, sigmoid, relu
nh1	Number of hidden layer cells in the F1 block. Approximately equal to number of inputs, len(COL_U).
	type	integer
nh2	Number of hidden layer cells in the F2 block. Approximately equal to number of outputs, len(COL_Y).
	type	integer
COL_T	Time point channel name, usually t
	type	array
	items	type	string
	maxItems	1
	minItems	1
COL_U	Input channel names, minimally Vd and Vq for a Norton model, or Id and Iq for a Thevenin model. Usually G, T, Ctl, Fc, Ud, Uq, GVrms for a Norton model, GIrms for a Thevenin model.
	type	array
	items	type	string
	minItems	2
COL_Y	Output channel names, minimally Id and Iq for a Norton model, or Vd and Vq for a Thevenin model. Usually Vdc and Idc.
	type	array
	items	type	string
	minItems	2

Normalization Factors

https://github.com/pnnl/pecblocks/docs/normalization.json
Map all channels to the range 0-1 per-unit. pu = val scale + offset* This object is unnamed in a standalone normfacs.json file. Must be named normfacs when part of a model_fhf.json file.
type	object
additionalProperties	type	object
	properties
	scale	Scaling factor or weight. After normalization, the range will be 1.0 over all times and records.
		type	number
	offset	Mean channel value over all times and records. Defines the bias or offset in normalization.
		type	number
	min	Minimum channel value over all times and records.
		type	number
	max	Maximum channel value over all times and records.
		type	number

Sensitivity Losses

https://github.com/pnnl/pecblocks/docs/sensitivity.json
Add sensitivity losses to the fitting loss. The name of this object must be sensitivity.
type	object
properties
limit	Maximum value for partial derivatives, outputs w.r.t. inputs Units are ohms for a Norton model, mhos for a Thevenin model. (Deprecated in favor of the weight attribute because a stiff limit causes discontinuity in fitting loss vs. epoch).
	type	number
weight	Per-unit multiplier for sensitivity loss added to fitting loss contributions to the total loss in each epoch. Use 0.001 as a starting value, then adjust so that contributions of the fitting and sensitivity losses, as shown in the log, are about equal.
	type	number
delta	Change in the input values used to numerically estimate partial derivatives, outputs w.r.t. inputs. Units are the same as for input columns. Use about 0.001 of the input range.
	type	number
inputs	max
	Column or channel names from COL_U. Typically Vd and Vq for a Norton model. Typically Id and Iq for a Thevenin model.
	type	array
	items	type	string
	maxItems	2
	minItems	2
outputs	max
	Column or channel names from COL_Y. Typically Id and Iq for a Norton model. Typically Vd and Vq for a Thevenin model.
	type	array
	items	type	string
	maxItems	2
	minItems	2
GIrms	Defines the polynomial feature for Thevenin models. This input varies with Id and Iq. Unused for Norton models.
	type	object
	properties
	G	Name of solar irradiance input channel, e.g., G
		type	string
	Id	Name of d-axis current input channel, e.g., Id
		type	string
	Iq	Name of q-axis current input channel, e.g., Iq
		type	string
	k	Multiplier for Irms from Id and Iq. Use sqrt(3/2) for three-phase, 1 for single-phase.
		type	number
GVrms	Defines the polynomial feature for Norton models. This input varies with Vd and Vq. Unused for Thevenin models.
	type	object
	properties
	G	Name of solar irradiance input channel, e.g., G
		type	string
	Vd	Name of d-axis voltage input channel, e.g., Vd
		type	string
	Vq	Name of q-axis voltage input channel, e.g., Vq
		type	string
	k	Multiplier for Vrms from Vd and Vq. Use sqrt(3/2) for three-phase, 1 for single-phase.
		type	number
sets	Defines the baseline operating points for evaluating the model sensitivities, i.e., partial derivatives of the outputs w.r.t. inputs at each epoch. There should be one set for each channel in COL_U, excluding the polynomial feature GVrms or GIrms. Polynomial features are calculated from the other channels.
	type	object
	additionalProperties	Data values to use for this input channel in evaluating the sensitivity. Use judiciously to avoid combinatorial explosion.
		type	array
		items	type	number
		minItems	1

Clamping Losses

https://github.com/pnnl/pecblocks/docs/clamping.json
Add clamping losses to the fitting loss. The name of this object must be clamping.
type	object
additionalProperties	Define one set of limits for each output channel. First value is minimum, second value is maximum.
	type	array
	items	type	number
	maxItems	2
	minItems	2

Block F1 or F2

https://github.com/pnnl/pecblocks/docs/blockF1.json
Neural network layers for static nonlinearities.
type	object
properties
n_in	Number of input channels for this block.
	type	integer
	minimum	1
n_hid	Number of neurons in the hidden layer.
	type	integer
	minimum	1
n_out	Number of output channels for this block.
	type	integer
	minimum	1
activation	Activation function type for the neurons.
	type	string
	enum	tanh, sigmoid, relu
net.0.weight	2D array of weights for the input layer, n_hid rows.
	type	array
	items	n_in columns
		type	array
		items	type	number
net.0.bias	1D array of bias values for the input layer, n_hid rows.
	type	array
	items	type	number
net.2.weight	2D array of weights for the output layer, n_out rows.
	type	array
	items	n_hid columns
		type	array
		items	type	number
net.2.bias	1D array of bias values for the output layer, n_out rows.
	type	array
	items	type	number

Block H1

https://github.com/pnnl/pecblocks/docs/blockH1.json
Multiple-input multiple-output (MIMO) transfer functions for H1(z) in discrete time domain. Defined pair-wise between input and output channels.
type	object
properties
n_in	Number of input channels for this block.
	type	integer
	minimum	1
n_out	Number of output channels for this block.
	type	integer
	minimum	1
n_b	Number of learnable numerator coefficients in each H(z).
	type	integer
	minimum	1
n_a	Number of learnable denominator coefficients in each H(z). In addition, a0=1 should be included; it’s not learnable.
	type	integer
	minimum	1
n_k	Number of delay steps in the output.
	type	integer
	minimum	0
additionalProperties	Defines the coefficients by increasing order of z^(-1). Numerator coefficients are in objects named b_i_j, and Denominator coefficients are in objects named a_i_j, where i is the output channel number, 0..n_out-1, and j is the input channel number, 0..n_in-1. (For stable2nd and stable2ndx models, the named objects alpha1_i_j and alpha2_i_j also appear. These are defined for model training only, and not necessary for model evaluation. Their types are number, not array.)
	type	array
	items	type	number
	minItems	1

Block H1s

https://github.com/pnnl/pecblocks/docs/blockH1s.json
Multiple-input multiple-output (MIMO) transfer functions for H1(s) in continuous time domain. Defined pair-wise between input and output channels.
type	object
properties
n_in	Number of input channels for this block.
	type	integer
	minimum	1
n_out	Number of output channels for this block.
	type	integer
	minimum	1
n_b	Number of numerator coefficients in each H(s).
	type	integer
	minimum	1
n_a	Number of denominator coefficients in each H(s).
	type	integer
	minimum	1
additionalProperties	Defines the coefficients by increasing order of s, beginning with 0. Numerator coefficients are in objects named b_i_j, and Denominator coefficients are in objects named a_i_j, where i is the output channel number, 0..n_out-1, and j is the input channel number, 0..n_in-1.
	type	array
	items	type	number
	minItems	1

Block Q1s

https://github.com/pnnl/pecblocks/docs/blockQ1s.json
State transition matrices for H1(s) in continuous time domain. The state-space form is Ax_dot + Bu = x, y = Cx + Du. These are serialized as numpy arrays, squeezed to lists which cannot be validated in JSON Schema. Defined pair-wise between multiple input and multiple output (MIMO) channels.
type	object
properties
n_in	Number of input channels for this block.
	type	integer
	minimum	1
n_out	Number of output channels for this block.
	type	integer
	minimum	1
n_b	Number of columns in the A matrix.
	type	integer
	minimum	1
n_a	Number of rows in the A matrix.
	type	integer
	minimum	1
additionalProperties	Matrices in objects named A_i_j, B_i_j, C_i_j, and D_i_j, where i is the output channel number, 0..n_out-1, and j is the input channel number, 0..n_in-1.
	type	numpy array
	items	type	number
	minItems	1