Rev Contribution

custom reV errors/exceptions

<2026-04-10 Fri>

story

implement custom rev exceptions to replace base exceptions

unused exceptions

• SlurmWarning
• SAMExecutionWarning
• ExtrapolationWarning
• NearestNeighborError
• JSONError

SAM

SAM.py

• SAMExecutionError
  • _get_basehandler - get base SAM resource handler
    • raises error if module not found
  • execute - call PySAM execute method
    • raises error if execution fails for some reason
  • collect_outputs - collect SAM output_request -> convert time-series outputs to UTC -> save outputs to self.outputs
    • raises error if bad request from PySAM object
• SAMInputWarning
  • _make_reskwargs - make Resource.preloadSam args and kwargs
    • raise warning if downscaling is request for any resource handler that is not NSRDB
  • assign_inputs - assign a flat dict of inputs to the PySAM object
    • raise warning for inputs that are not set because they are not found in PySAM object
• SAMInputError
  • set_item - set a PySAM input data attribute
    • raises error if attribute not found
    • catches error from `setattr(getattr(self.pysam, group), key, value)`
• ResourceError
  • ensure_reslen - ensure time_index has a constant time-step and only covers 365 days (no leap days)
    • raises error if time_index does not have a consistent time-step

econ.py

• SAMExecutionError
  • parse_syscap - find the system capacity variable in either inputs or dataframe
    • raises error uf system capacity or turbine capacity is not included in the site-specific inputs in order to calculate annual energy yield for LCOE
• KeyError
  • _get_cfprofiles - get the multi-site capacity factor time series profiles
    • raises error if cf_profile values are not found
  • _parse_lcoeinputs - parse for non-site-specific LCOE inputs
    • raises error if cf_mean values are not found for LCOE calculation

windbos.py

• SAMInputError

defaults.py

• NotImplementedError

generation.py

• InputError
  • multiple vals for `temperature` for site
  • "" `potential<sub>MW</sub>` ""
  • found nan vals for site {} in vars {}
• SAMExecutionError
• NotImplementedError
• ValueError
  • lat/lon exception

version_checker.py

• PySAMVersionError
• PySAMVersionWarning

bespoke

bespoke.py

• ValueError
  • Unknown dataset name
• TypeError
  • min_spacing must be numeric
• KeyError
  • user requested "lcoe_fcr" but did not input "fixed_chargerate" in SAM system config
  • could not find LCOE kwargs in outputs; plant_optimizer, original_samsysinputs, or meta
• ModuleNotFoundError
• RuntimeError
  • failed while running SAM windpower timeseries analysis
  • failed while running turbine placement optimizer
  • SC gid xxx failed
• FileNotFoundError
  • exclusions file not found
• FileInputError
  • techmap dataset not found in exclusions file
• OSError

pack_turbs.py

• WhileLoopPackingError

place_turbines.py

• ValueError
  • will not eval string which contains xxx
• WhileLoopPackingError

config

base_config.py

• ConfigError
  • init_config - initialize and load config from file
    • raises error if config file does not exist or cannot be parsed
• IOError
  • init_config - initialize and load config from file
    • raises error when config file path cannot be read

project_points.py

• ConfigError
  • parse - parse project points from file or object
    • raises error when project points file type is not recognized
  • from_range - create project points from a range of gids
    • raises error if sites argument has invalid form
• ValueError
  • parse_tech - parse the technology from the project points config
    • raises error if more than one unique technology is found in project points
• TypeError
  • parse - parse project points from file or object
    • raises error when project points input type is not recognized
• KeyError
  • sam_configobj - get the SAM config object for a given gid
    • raises error if gid not found in SAM config mapping
• RuntimeError
  • split - split project points into sub-chunks
    • raises error when project points cannot be split into the requested number of chunks

execution.py

• ConfigError
  • parse_{executioncontrol} - parse execution control from config
    • raises error if required execution control parameters are missing or invalid

econ

econ.py

• Exception
  • run_singleworker - run a single econ worker for a set of sites
    • raises base exception if `econ<sub>fun</sub>` fails during SAM econ execution
• ExecutionError
  • parse_{outputrequest} - parse and validate user output requests
    • raises error if none of the user output requests are recognized
  • get_datashape - get the output data shape from SAM config
    • raises error if non-scalar site_data input key is passed as an output_request
• ValueError
  • parse_{outputrequest} - parse and validate user output requests
    • raises error if econ outputs requested span incompatible SAM modules
• Exception
  • run - run econ analysis for all sites
    • raises base exception if analysis sites from project points are not found in cf file
    • raises base exception if SmartParallelJob execution fails

cli_econ.py

• IOError
  • parse_cffiles - parse capacity factor files for econ
    • raises error if a cf file does not exist on disk
• ConfigError
  • parse_cffiles - parse capacity factor files for econ
    • raises error if the number of cf files does not match the number of analysis years
    • raises error if a requested analysis year cannot be found in the cf files

economies_ofscale.py

• TypeError
  • preflight - run preflight checks on input data
    • raises error if data input is not a dict or DataFrame
• KeyError
  • preflight - run preflight checks on input data
    • raises error if variables required for an equation are missing from input data
  • get_{prioritizedkeys} - get keys from input dict by priority order
    • raises error if none of the requested keys are found in the input dict
• ValueError
  • preflight - run preflight checks on input data
    • raises error if equation string evaluates to an invalid value

generation

base.py

• Exception
  • out.setter - set site output results
    • raises base exception if site results are non-sequential
• TypeError
  • out.setter - set site output results
    • raises error if output type is unrecognized
  • output_{requesttypecheck} - validate the output_request argument type
    • raises error if output_request is not str, list, or tuple
• ValueError
  • handle_leapti - handle leap year time index by dropping Feb 29
    • raises error if time index length is not a multiple of 365
  • site_index - get or set the current site index
    • raises error if output_index is negative (site index already set)
  • patch_{wavegenpysam5} - patch wave generation output for PySAM 5
    • raises error if non-zero values are found at the end of the generation array
• Exception
  • parse_sitedata - parse site-specific SAM input data from csv or DataFrame
    • raises base exception if site data input is not a .csv or DataFrame
• KeyError
  • parse_sitedata - parse site-specific SAM input data from csv or DataFrame
    • raises error if gid column is missing from site data
  • get_pc - get the points control object for a given technology
    • raises error if the technology string is not recognized
• ExecutionError
  • get_{datashapefromsamconfig} - get output data shape from SAM config
    • raises error if a non-scalar SAM input key is passed as an output_request
  • get_{datashapefrompysam} - get output data shape from PySAM object
    • raises error if the requested dataset is not found in the PySAM object

cli_gen.py

• ConfigError
  • parse_resfiles - parse resource files from generation config
    • raises error if resource_file is not a recognized type
    • raises error if resource file count does not match the number of analysis years

generation.py

• KeyError
  • init - initialize the generation object
    • raises error if the technology string is not in OPTIONS dict
• ProjectPointsValueError
  • meta - get the resource meta data for analysis sites
    • raises error if the max site gid exceeds the resource meta data length
• ConfigError
  • handle_{lifetimeindex} - handle lifetime index for multi-year modeling
    • raises error if multiple analysis_periods are found in the config
    • raises error if invalid output arrays are requested alongside lifetime modeling
• Exception
  • run_singleworker - run a single generation worker for a set of sites
    • raises base exception if `cls.OPTIONS[tech].reV<sub>run</sub>` fails
  • run - run generation for all sites with parallel execution
    • raises base exception if generation execution fails
• InputError
  • parse_gidmap - parse optional gid map to remap resource gids to supply curve gids
    • raises error if the gid_map file cannot be parsed

handlers

exclusions.py

• TypeError
  • init - initialize exclusions handler
    • raises error if h5_file is not str, list, or tuple
• MultiFileExclusionError
  • preflight_multifile - run preflight checks for multi-file exclusions
    • raises error if a layer shape does not match lat/lon shapes
    • raises error if multi-file exclusions do not have matching coordinate profiles
• HandlerKeyError
  • get_latitude - get latitude array from h5 file
    • raises error if latitude dataset is missing from h5 file
  • get_longitude - get longitude array from h5 file
    • raises error if longitude dataset is missing from h5 file
  • get_layer - get a single exclusion layer from h5 file
    • raises error if requested layer is not in available layers

multi_year.py

• ConfigError
  • source_files (MultiYearGroup) - get list of source files for multi-year aggregation
    • raises error if source_files is not a list, tuple, or "PIPELINE"
    • raises error if neither source_files nor source_dir+source_prefix are provided
• CollectionRuntimeError
  • source_files (MultiYearGroup) - get list of source files for multi-year aggregation
    • raises error if source_pattern glob results in non-h5 files
  • parse_{sourcefilespattern} - parse source files from a glob pattern
    • raises error if non-h5 files are found in the pattern results
• FileNotFoundError
  • source_files (MultiYearGroup) - get list of source files for multi-year aggregation
    • raises error if no source files are found matching the pattern
• TypeError
  • parse_{sourcefilespattern} - parse source files from a glob pattern
    • raises error if source_files type is not recognized
• HandlerRuntimeError
  • copy_dset - copy a dataset across source files into multi-year output
    • raises error if meta data lengths differ across source files
  • compute_means - compute multi-year means for a dataset
    • raises error if dataset shapes do not match across source files
  • compute_stdev - compute multi-year standard deviation for a dataset
    • raises error if dataset shapes do not match across source files
• CollectionValueError
  • is_profile - check if dataset is a time-series profile
    • raises error if requested dataset is not found in the source file
• CollectionWarning
  • copy_dset - copy a dataset across source files into multi-year output
    • warns if coordinates do not match between collection files
  • my_{collectgroups} - collect all groups into a single multi-year HDF5 file
    • warns when an existing multi-year output file is found and removed (clobber)

transmission.py

• HandlerKeyError
  • getitem - get feature data by gid
    • raises error if the feature gid is invalid
  • features_fromtable - build features dict from a transmission table
    • raises error if feature type is not recognized
  • substation_capacity - get capacity available at a substation
    • raises error if capacities are not found for the substation
• ValueError
  • features_fromtable - build features dict from a transmission table
    • raises error if features dict input is not valid
• RuntimeError
  • check_{featuredependencies} - check that parent features exist for substations
    • raises error if parent features depend on missing transmission lines
  • connect - connect a supply curve point to a transmission feature
    • raises error if needed capacity exceeds available capacity
• HandlerRuntimeError
  • available_capacity - get available capacity at a transmission feature
    • raises error if available capacity cannot be parsed from the feature data
• NotImplementedError
  • POIFeatures.cost - compute connection cost for POI features
    • raises error because cost computation is not supported for POI features
  • POIFeatures._calccost - internal cost calculation for POI features
    • raises error because POI cost calculation is not implemented

losses

power_curve.py

• reVLossesValueError
  • PowerCurve._{validatewindspeed} - validate wind speed input array
    • raises error if wind speed contains negative values
  • PowerCurve._{validategeneration} - validate generation output array
    • raises error if there are no positive generation values in the power curve
    • raises error if non-zero generation values exist above the cutoff wind speed
  • PowerCurveLosses._{validatewindresource} - validate wind resource input
    • raises error if wind resource contains negative values
  • PowerCurveLosses._{validateweights} - validate bin weights for wind resource
    • raises error if weights size does not match wind resource size
  • PowerCurveLossesInput._{validaterequiredkeysexist} - validate required keys in loss spec
    • raises error if required keys are missing from the loss specification
  • PowerCurveLossesInput._{validatetransformation} - validate transformation name
    • raises error if transformation name is not in TRANSFORMATIONS dict
  • PowerCurveLossesInput._{validatepercentage} - validate loss percentage value
    • raises error if percentage is not in the range [0, 100]
  • PowerCurveWindResource.wind_{resourceforsite} - get wind resource for a single site
    • raises error if pressure units cannot be determined from dataset
  • AbstractPowerCurveTransformation._{validatenonzerogeneration} - validate transformed power curve
    • raises error if the calculated power curve is invalid (all zeros or negative)
  • AbstractPowerCurveTransformation._{validatesamecutoff} - validate cutoff wind speeds match
    • raises error if cutoff wind speeds of original and transformed curves don't match
  • PowerCurveLossesMixin.wind_{resourcefrominput} - get wind resource from user input
    • raises error if wind_{resourcemodelchoice} is incompatible with input type
• NotImplementedError
  • AbstractPowerCurveTransformation.apply - apply the power curve transformation
    • raises error when subclass has not set _{transformedgeneration}

utils.py

• reVLossesValueError
  • validate_{arraysnotempty} - validate that input data arrays are not empty
    • raises error if an input data array is empty

scheduled.py

• reVLossesValueError
  • Outage._{validaterequiredkeysexist} - validate required keys in outage spec
    • raises error if required keys are missing from the outage specification
  • Outage._{validatecount} - validate outage count value
    • raises error if count is not an integer or is less than 1
  • Outage._{validateandconverttofullnamemonths} - validate and normalize month names
    • raises error if no recognized month names are provided
  • Outage._{validateduration} - validate outage duration value
    • raises error if duration is not an integer or is outside the valid range
  • Outage._{validatepercentage} - validate outage loss percentage
    • raises error if percentage is not in the range (0, 100]

nrwal

nrwal.py

• KeyError
  • parse_sitedata - parse and validate site data input
    • raises error if required columns (gid, config) are missing from site_data
• OffshoreWindInputError
  • preflight_checks - run preflight validation checks
    • raises error if config ids in site_data are missing from the NRWAL config input
    • raises error if site_metacols are not found in site_data
  • get_inputdata - get input data arrays for NRWAL analysis
    • raises error if required NRWAL input variables are not found in gen outputs or meta
• DataShapeError
  • get_inputdata - get input data arrays for NRWAL analysis
    • raises error if data shape is not 1D or 2D
  • save_nrwalout - save NRWAL output arrays to the output file
    • raises error if a 1D output is found to be 2D but not all-NaN
    • raises error if NRWAL output shape cannot be understood
• TypeError
  • value_toarray - convert a NRWAL output value to a numpy array
    • raises error if a NRWAL key returns a value of an unrecognized type

qa_qc

qa_qc.py

• TypeError
  • QaQcModule.__init___ - initialize the QA/QC module handler
    • raises error if config input is not a dict
• PipelineError
  • QaQcModule.fpath - get the file path for the module output
    • raises error if fpath cannot be parsed from previous pipeline jobs

rep_profiles

rep_profiles.py

• FileInputError
  • RepProfilesBase._{parserevsummary} - parse the reV summary CSV file
    • raises error if the reV summary file cannot be parsed
• TypeError
  • RepProfilesBase._{parserevsummary} - parse the reV summary CSV file
    • raises error if rev_summary input is not a valid dtype (str path or DataFrame)
• KeyError
  • RepProfilesBase._checkreqcols - check that required columns exist in the summary table
    • raises error if required column labels are not found in the rev_summary table
  • RepProfilesBase._checkrevgen - check that the gen file has required datasets
    • raises error if cf_dset is not in the gen file datasets
    • raises error if time_index is not in the gen file datasets
• DataShapeError
  • RegionRepProfile._{runrepmethods} - run representative profile methods for a region
    • raises error if the weights column length doesn't match the profiles shape
• ValueError
  • RepProfiles.__init___ - initialize representative profiles
    • raises error if reg_cols is None

supply_curves

aggregation.py

• RuntimeError
  • run_serial / run_parallel - run supply curve aggregation
    • raises error if aggregation fails for a supply curve point
• SupplyCurveInputError
  • check_files - check that required input files exist
    • raises error if required exclusions or resource files are not found
• FileInputError
  • check_files - check that required input files exist
    • raises error if techmap dataset is not found in the exclusions file
• FileNotFoundError
  • check_files - check that required input files exist
    • raises error if the exclusions h5 file does not exist
• EmptySupplyCurvePointError
  • run_single - run aggregation for a single supply curve point
    • raises error if no valid resource pixels are found within the supply curve cell

sc_aggregation.py

• FileInputError
  • check_exclfiles - check exclusion file inputs
    • raises error if the techmap dataset is not found in the exclusions file
• TypeError
  • parse_scpoints - parse supply curve points
    • raises error if sc_points input type is not recognized
• KeyError
  • parse_cfdset - parse capacity factor dataset name
    • raises error if cf_dset is not found in the resource file
• ValueError
  • check_resfile - check resource file is valid
    • raises error if resource file does not contain required datasets
• EmptySupplyCurvePointError
  • run_single - run aggregation for a single supply curve point
    • raises error if supply curve point has no valid resource data

supply_curve.py

• KeyError
  • parse_scpoints - parse supply curve points from input
    • raises error if required columns are missing from the supply curve table
• RuntimeError
  • run - run supply curve transmission mapping
    • raises error if supply curve execution fails
• SupplyCurveInputError
  • check_sctable - validate the supply curve table
    • raises error if required columns are missing or invalid in the supply curve table
• SupplyCurveError
  • full_sort - sort supply curve by LCOE with transmission costs
    • raises error if supply curve sorting fails unexpectedly

competitive_windfarms.py

• RuntimeError
  • remove_{noncompetitivewindfarms} - remove wind farms that are not cost-competitive
    • raises error if the competitive wind farm removal process fails
• ValueError
  • parse_winddirs - parse wind direction data for competitive analysis
    • raises error if wind direction input is invalid

points.py

• IndexError
  • SupplyCurvePoint.__init__ - initialize a supply curve point
    • raises error if the supply curve gid is out of range
• SupplyCurveInputError
  • SupplyCurvePoint._{parseresources} - parse resource data for the point
    • raises error if required resource inputs are missing or invalid
• EmptySupplyCurvePointError
  • SupplyCurvePoint._checkexcl - check exclusion data for the point
    • raises error if no valid (non-excluded) pixels remain in the supply curve cell
• ValueError
  • SupplyCurvePoint._parselatlon - parse lat/lon for the supply curve point
    • raises error if latitude or longitude cannot be determined
• DataShapeError
  • SupplyCurvePoint._{parsedatashape} - parse expected output data shape
    • raises error if resource and exclusion data shapes do not match
• FileInputError
  • SupplyCurvePoint._parsetechmap - parse technology mapping from exclusions file
    • raises error if techmap dataset is not found in the exclusions file
• TypeError
  • SupplyCurvePoint._parseinput - parse a generic input for the supply curve point
    • raises error if input type is not recognized

exclusions.py

• ValueError
  • LayerMask._{parseinclusionweights} - parse inclusion weights for a layer
    • raises error if inclusion weight values are invalid
• ExclusionLayerError
  • LayerMask.__init__ - initialize a layer mask
    • raises error if the layer configuration is invalid
• KeyError
  • ExclusionMask._getlayer - get a layer from the exclusions file
    • raises error if a requested layer is not found in the exclusions h5 file
• SupplyCurveInputError
  • ExclusionMaskFromDict._parselayer - parse a single exclusion layer from dict
    • raises error if layer specification dict is invalid

tech_mapping.py

• FileInputError
  • map_{tosupplycurve} - map resource pixels to supply curve points
    • raises error if techmap dataset is not found in the exclusions file

utilities

curtailment.py

• KeyError
  • Curtailment._parse - parse curtailment parameters from config
    • raises error if required curtailment parameter keys are missing from the config

implementation

• Browse the different modules and note base exceptions and/or scenarios where an exception may be acceptable and valuable to users downstream
  • identify existing uses of custom exceptions and base exceptions
• Replace/Modify exceptions one module at a time.

testing

foresight

certificate of origin

When AI tools contribute to development, proper attribution helps track the evolving role of AI in the development process. Contributions should include an Assisted-by tag in the following format:

Assisted-by: AGENT_NAME:MODEL_VERSION [TOOL1] [TOOL2]

Where:

• AGENT_NAME is the name of the AI tool or framework
• MODEL_VERSION is the specific model version used
• [TOOL1] [TOOL2] are optional specialized analysis tools used (e.g., coccinelle, sparse, smatch, clang-tidy)
• Basic development tools (git, editors) should not be listed

This contribution:

Assisted-by: Claude:claude-sonnet-4-6 [grep] [glob]

comments

• “User code can raise built-in exceptions. This can be used to test an exception handler or to report an error condition “just like” the situation in which the interpreter raises the same exception; but beware that there is nothing to prevent user code from raising an inappropriate error.”

• “ It’s recommended to only subclass one exception type at a time to avoid any possible conflicts between how the bases handle the args attribute, as well as due to possible memory layout incompatibilities.”

• Allows downstream users of reV to catch reV exceptions explicitly