pvdeg.scenario#

Scenario objects and methods for accelerated analysis.

Classes#

class pvdeg.scenario.Scenario(name: str | None = None, path: str | None = None, gids: int | List[int] | ndarray[int] | None = None, modules: list | None = None, pipeline={}, file: str | None = None, results=None, weather_data: DataFrame | None = None, meta_data: dict | None = None, email: str | None = None, api_key: str | None = None)[source]#

Bases: object

Scenario object, contains all parameters and criteria for a given scenario.

Generally speaking, this will be information such as: Scenario Name, Path, Geographic Location, Module Type, Racking Type

clean()[source]#

Wipe the Scenario object filetree.

This is useful because the Scenario object stores its data in local files outside of the python script. This causes issues when two unique scenario instances are created in the same directory, they appear to be seperate instances to python but share the same data (if no path is provided). Changes made to one are reflected in both.

Parameters:#

None

See Also:#

pvdeg.utilties.remove_scenario_filetree to remove all pvd_job_* directories and children from a directory

addLocation(lat_long: tuple = None, weather_db: str = 'PSM4')[source]#

Add a location to the scenario using a latitude-longitude pair.

The scenario object instance must already be populated with credentials when making a call to the NSRBD. Provide credentials during class intialization or using Scenario.restore_credentials

Parameters:#

lat-longtuple

tuple of floats representing a latitude longitude coordinate. >>> (24.7136, 46.6753) #Riyadh, Saudi Arabia

weather_dbstr

source of data for provided location. - For NSRDB data use weather_db = ‘PSM4’ - For PVGIS data use weather_db = ‘PVGIS’

addModule(module_name: str = None, racking: str = 'open_rack_glass_polymer', materials: str | dict = 'OX003', material_file: str = 'O2permeation', parameters: list | None = None, temperature_model: str = 'sapm', model_kwarg: dict = {}, irradiance_kwarg: dict = {})[source]#

Add a module to the Scenario. Multiple modules can be added. Each module will be tested in the given scenario.

Parameters:

  • module_name (str) – unique name for the module. adding multiple modules of the same name will replace the existing entry.

  • racking (str) – temperature model racking type as per PVLIB (see pvlib.temperature). Allowed entries: ‘open_rack_glass_glass’, ‘open_rack_glass_polymer’, ‘close_mount_glass_glass’, ‘insulated_back_glass_polymer’

  • materials (Union[str, dict]) – Materials specification. Can be either: - str: Single material key e.g., “OX003” - dict: Nested dictionary with structure PV layer, materials file, material key, and parameters if custom material is specifed. For example:

  • { –

    “encapsulant”: {

    “material_file”: “O2permeation”, “material_name”: “OX003”

    }, “backsheet”: {

    ”material_file”: “H20permeation”, “material_name”: “W024”

    }, “custom_layer”: {

    ”parameters”: {

    “Ead”: 95, “Do”: 40e5, “Eas”: -10, “So”: 20e-6, “Eap”: 84, “Po”: 99e9

    }

    }

  • }

  • material_file (str) – Material file used to access parameters if material_name exists in one of the local material json databases. Options: >>> “AApermeation”, “H2Opermeation”, “O2permeation”

  • parameters (list) – List of parameter names to retrieve from the material database. If None, all parameters are retrieved. This argument is passed to the parameters argument of utilities._read_material.

  • temperature_model (list[str]) – select pvlib temperature models. See pvdeg.temperature.temperature for more. Options : 'sapm', 'pvsyst', 'faiman', 'faiman_rad', 'fuentes', 'ross'

  • model_kwarg (dict, (optional)) – provide a dictionary of temperature model coefficents to be used instead of pvlib defaults. Some models will require additional arguments such as ross which requires nominal operating cell temperature (noct). This is where other values such as noct should be provided. pvlib-python temperature models: https://pvlib-python.readthedocs.io/en/stable/reference/pv_modeling/temperature.html # noqa

  • irradiance_kwarg (dict, (optional)) – provide keyword arguments for poa irradiance calculations. Options : sol_position, tilt, azimuth, sky_model

add_material(materials, see_added=False)[source]#

Add new material types to multiple layers/files.

Parameters:#

materialsdict

Dictionary with layer names as keys, and material info including: - material_file: str - Name of the material file (e.g., “O2permeation”)

  • required only for existing materials

  • material_name: str - Name of the material to add

  • parameters: dict - Custom material parameters (for custom materials)

Example:#

scenario.add_material({
“encapsulant”: {

“material_file”: “O2permeation”, “material_name”: “EVA_001”

}, “backsheet”: {

“material_file”: “H2Opermeation”, “material_name”: “PET_001”

}, “custom_layer”: {

“material_name”: “CUSTOM_001”, “parameters”: {

“Ead”: 95, “Do”: 40e5, “Eas”: -10, “So”: 20e-6, “Eap”: 84, “Po”: 99e9

}

}

})

viewScenario()[source]#

Print all scenario information currently stored in the scenario instance.

Does not implement ipython.display. If available, use this.

addJob(func=None, func_kwarg={})[source]#

Add a pvdeg function to the scenario pipeline.

Parameters:#

funcfunction

pvdeg function to use for single point calculation. All regular pvdeg functions will work at a single point when Scenario.geospatial == False

func_paramsdict

job specific keyword argument dictionary to provide to the function

run()[source]#

Run all jobs in pipeline on scenario object for each module in the scenario.

Note: if a pipeline job contains a function not adhering to package wide pv parameter naming scheme, the job will raise a fatal error.

Parameters:#

None

Returns:#

None

classmethod load_json(file_path: str = None, email: str | None = None, api_key: str | None = None)[source]#

Import scenario dictionaries from existing ‘scenario.json’ file.

classmethod remove_scenario_filetrees(pattern='pvd_job_*')[source]#

Move cwd to fp and remove all scenario file trees from fp directory.

Permanently deletes all scenario file trees. USE WITH CAUTION.

Parameters:#

fpstring

file path to directory where all scenario files should be removed

patternstr

pattern to search for using glob. Default value of pvd_job_ is equvilent to pvd_job_* in bash.

returns:

None

See also

None

dump(api_key: bool = False, path: str | None = None) → None[source]#

Serialize the scenario instance as a json.

No dataframes will be saved but some attributes like weather_df and results will be stored in nested file trees as csvs.

Parameters:#

api_keybool, default=``False``

Save api credentials to json. Default False. Use with caution.

pathstr

location to save. If no path provided save to scenario directory.

restore_credentials(email: str, api_key: str) → None[source]#

Restore email and api key to scenario.

Use after importing scenario if json does not contain email and api key.

Parameters:

  • email (str) – email associated with nsrdb developer account

  • api_key (str) – api key associated with nsrdb developer account

extract(dim_target: Tuple[str, str], col_name: str | None = None, tmy: bool = False, start_time: datetime | None = None, end_time: datetime | None = None) → DataFrame[source]#

Extract scenario results along an axis.

Note

Only works if results are of the same shape. Ex) running 5 different temperature calculations on the same module. Counter Ex) running a standoff and tempeature calc on the same module.

Ex: (‘function’ : ‘AKWMC)

Parameters:

  • dim_target (tuple of str) –

    Define a tuple of (dimension, name) to select results. The dimension is either ‘function’ or ‘module’, and the name is the name of the function or module to grab results from.

    Note: Receives job ID, not function name in dim_target.

    Dimension options: ‘function’, ‘module’

    Examples: To grab ‘standoff’ result from all modules in the scenario: Determine the name of the standoff job using display(Scenario). If the job is called AJCWL, the result would be: dim_target = (‘function’, ‘AJCWL’)

    To grab all results from a module named ‘mod_a’: dim_target = (‘module’, ‘mod_a’)

  • col_name (Optional[str], default = None) – The column name to extract. Only use when results contain dataframes with multiple columns. Extranious if results are pd.Series or single numeric values.

  • tmy (bool, default False) – Whether to use typical meteorological year data.

  • start_time (Optional[dt.datetime], default None) – The start time for the data extraction.

  • end_time (Optional[dt.datetime], default None) – The end time for the data extraction.

plot(dim_target: Tuple[str, str], col_name: str | None = None, tmy: bool = False, start_time: datetime | None = None, end_time: datetime | None = None, title: str = '') → tuple[source]#

Plot scenario results along an axis using Scenario.extract.

Note:#

only works if results are of the same shape. Ex) running 5 different temperature calculations on the same module. Counter Ex) running a standoff and tempeature calc on the same module.

Ex: (‘function’ : ‘AKWMC)

Parameters:#

dim_targettuple of str

Define a tuple of (dimension, name) to select results. The dimension is either ‘function’ or ‘module’, and the name is the name of the function or module to grab results from.

Note: Receives job ID, not function name in dim_target.

Dimension options: ‘function’, ‘module’

Examples: To grab ‘standoff’ result from all modules in the scenario: Determine the name of the standoff job using display(Scenario). If the job is called AJCWL, the result would be: dim_target = (‘function’, ‘AJCWL’)

To grab all results from a module named ‘mod_a’: dim_target = (‘module’, ‘mod_a’)

col_name: Optional[str], default = None

The column name to extract. Only use when results contain dataframes with multiple columns. Extranious if results are pd.Series or single numeric values.

tmy: bool, default False

Whether to use typical meteorological year data.

start_time: Optional[dt.datetime], default None

The start time for the data extraction.

end_time: Optional[dt.datetime], default None

The end time for the data extraction.

title: Optional[str], default ‘’

Name of the matplotlib plot

Returns:#

fig, ax: tuple

matplotlib figure and axis objects

See Also:#

Scenario.extract To have more control over a plot simply extract the data and then use more specific plotting logic

format_modules()[source]#
format_results()[source]#
format_output(output)[source]#
format_weather()[source]#
format_pipeline()[source]#