Satcomp package

kaipy.satcomp.scRCM module

kaipy.satcomp.scRCM.consolidateODFs(scData, rcmTrackData, eGrid=None, doPlot=False)

Prepare the spacecraft and RCM track data for comparison.

Parameters:

  • scData (dict) – Dictionary containing spacecraft data.

  • rcmTrackData (dict) – Dictionary containing RCM track data.

  • eGrid (ndarray, optional) – Energy grid to use. If not provided, fixed bins spanning the full energy range will be created.

  • doPlot (bool, optional) – Whether to plot the data. Default is False.

Returns:

Dictionary containing the consolidated data.

Return type:

result (dict)

kaipy.satcomp.scRCM.genRCMTrack_jfname(jdir, scName)

Generate the JSON file name for RCM track.

Parameters:

  • jdir (str) – The directory where the JSON file will be located.

  • scName (str) – The name of the spacecraft.

Returns:

The full path of the JSON file name for RCM track.

Return type:

str

kaipy.satcomp.scRCM.genSCD_jfname(jdir, scName, dSetName)

Generates the JSON file name for a given satellite name and data set name.

Parameters:

  • jdir (str) – The directory where the JSON file will be located.

  • scName (str) – The name of the satellite.

  • dSetName (str) – The name of the data set.

Returns:

The generated JSON file name.

Return type:

str

kaipy.satcomp.scRCM.genVarNorm(var, doLog=False)

Generate normalized colorbar .

Parameters: - var: numpy array

The variable for which to generate normalized values.

  • doLog: bool, optional

    Flag indicating whether to use logarithmic normalization. Default is False.

Returns: - norm: normalized colorbar object.

kaipy.satcomp.scRCM.getIntensitiesVsL(rcmf5, mhdrcmf5, sStart, sEnd, sStride, species='ions', eGrid=None, jdir=None, forceCalc=False)

Calculate rcm intensities (summed diff flux).

Parameters:

  • rcmf5 (str) – RCM HDF5 filename to pull xmin, ymin, zmin from.

  • mhdrcmf5 (str) – MHDRCM HDF5 filename to pull IOpen from.

  • AxLvT (matplotlib.axes.Axes, optional) – If given, will plot the resulting L shell vs. time intensity.

  • jdir (str, optional) – Give JSON directory to enable JSON usage (read/write results to file).

  • forceCalc (bool, optional) – If dataset already found in file, re-calculate anyways and overwrite it.

Returns:

Dictionary containing the calculated intensities.

Return type:

result (dict)

kaipy.satcomp.scRCM.getRCM_CumulFrac(rcmf5, rcmTimes, evMJD, evalLatLon, species='ions', jdir=None, forceCalc=False)

Calculate cumulative fractions of certain vars (ex. pressure) over energy channels, for each list of points for each given MJD.

Parameters:

  • rcmf5 (str) – RCM HDF5 filename.

  • rcmTimes (dict) – Dictionary returned from getRCMTimes().

  • evMJDs (list) – List of MJDs to evaluate cumulative fractions.

  • evalLatLons (list) – List of [lat, lon] locations to perform calculation.

Returns:

Result data structure containing the following keys:

  • ’MJD’: MJD value.

  • ’i’: i value.

  • ’j’: j value.

  • ’lat’: Latitude value.

  • ’lon’: Longitude value.

  • ’xmin’: xmin value.

  • ’ymin’: ymin value.

  • ’vm’: vm value.

  • ’energies’: List of rcm energies [eV].

  • ’Ptot’: Total pressure.

  • ’Ppar’: List of each channel’s individual pressure.

  • ’Pcum’: List of each channel’s cumulative pressure (summing from k=0).

Return type:

dict

kaipy.satcomp.scRCM.getRCM_eqlatlon(mhdrcmf5, rcmTimes, sStart, sEnd, sStride, jdir=None, forceCalc=False)

Grab certain variables along with equatorial and lat-lon grid.

Parameters:

  • rcmf5 (str) – RCM HDF5 filename.

  • rcmTimes (dict) – Dictionary returned from getRCMTimes().

  • evMJDs (float) – MJD to evaluate cumulative fractions.

  • evalLatLons (list) – [lat, lon] location to perform calculation.

  • species (str, optional) – Species to calculate cumulative fractions for. Defaults to ‘ions’.

  • jdir (str, optional) – Directory to find JSON files in. Defaults to None.

  • forceCalc (bool, optional) – Force calculation even if JSON file exists. Defaults to False.

Returns:

A dictionary containing the calculated results.

Return type:

dict

Raises:

None –

kaipy.satcomp.scRCM.getRCM_scTrack(trackf5, rcmf5, rcmTimes, jdir=None, forceCalc=False, scName='')

Pull RCM data along a given spacecraft track.

Parameters:

  • trackf5 (str) – Path to the big spacecraft trajectory hdf5 file, generated from sctrack.x.

  • rcmf5 (str) – Path to the <tag>.rcm.h5 file.

  • rcmTimes (dict) – Dictionary containing RCM times information, including ‘sIDstrs’ and ‘MJD’.

  • jdir (str, optional) – If included, will try to do json saving and loading to save time. Defaults to None.

  • forceCalc (bool, optional) – Whether to force calculation even if json file exists. Defaults to False.

  • scName (str, optional) – Name of the spacecraft. Defaults to “”.

Returns:

Dictionary containing RCM data along the spacecraft track, including time, MJD, MLAT, MLON, vm, energy, and eetas.

Return type:

dict

kaipy.satcomp.scRCM.getRCMtimes(rcmf5, mhdrcmf5, jdir=None, forceCalc=False)

Grab RCM times, sIDs, and MJDs

Parameters:

  • rcmf5 (str) – Path to the RCM hdf5 file.

  • mhdrcmf5 (str) – Path to the MHDRCM hdf5 file.

  • jdir (str, optional) – Directory to search for JSON files. Defaults to None.

  • forceCalc (bool, optional) – Flag to force calculation even if JSON files exist. Defaults to False.

Returns:

Dictionary containing RCM time data.

Return type:

dict

Notes

  • If jdir is given, the function will try to find the files there. If not found, it will pull the data from the hdf5 files.

  • If JSON files exist and forceCalc is False, the function will load the data from the JSON files.

  • If JSON files do not exist or forceCalc is True, the function will calculate the RCM times based on the MHDRCM file.

kaipy.satcomp.scRCM.getSCOmniDiffFlux(scName, dSetName, t0, t1, jdir=None, forceCalc=False)

Retrieves spacecraft data and calculates omnidirectional differential flux.

Parameters:

  • scName (str) – Name of the spacecraft.

  • dSetName (str) – Name of the dataset.

  • t0 (float) – Start time of the data retrieval.

  • t1 (float) – End time of the data retrieval.

  • jdir (str, optional) – Directory to store the JSON file. Defaults to None.

  • forceCalc (bool, optional) – Flag to force calculation even if JSON file exists. Defaults to False.

Returns:

Ephemeris data. dataset (dict): Dataset containing the calculated omnidirectional differential flux.

Return type:

ephdata (dict)

Raises:

None –

Examples

# Retrieve spacecraft data and calculate omnidirectional differential flux ephdata, dataset = getSCOmniDiffFlux(“Satellite1”, “Dataset1”, 0, 10)

kaipy.satcomp.scRCM.getSpecieslambdata(rcmS0, species='ions')

Calculate lambdata for a given species in the RCM model.

Parameters:

  • rcmS0 (dict) – Dictionary containing RCM data.

  • species (str) – Species for which lambdata is calculated. Can be ‘ions’ or ‘electrons’. Default is ‘ions’.

Returns:

Dictionary containing the calculated lambdata.

Return type:

dict

kaipy.satcomp.scRCM.getVarCube(rcm5, varName, stepLow, stepHigh, ilon, ilat, k=None)
kaipy.satcomp.scRCM.getVarWedge(rcmf5, mhdrcmf5, sStart, sEnd, sStride, wedge_deg, species='ions', rcmTimes=None, eGrid=None, lGrid=None, jdir=None, forceCalc=False)

Take a slice/wedge centered along the x axis (eq space), calculate average <var> vs. L and E.

Parameters:

  • rcmf5 (str) – Filename of the RCM data in HDF5 format.

  • mhdrcmf5 (str) – Filename of the MHD RCM data in HDF5 format.

  • sStart (float) – Starting step value.

  • sEnd (float) – Ending step value.

  • sStride (float) – Step stride value.

  • width_deg (float) – Wedge width in degrees, centered around the x axis in the equatorial mapping of RCM data.

  • rcmTimes (dict) – Dictionary returned from the getRCMTimes() function.

  • eGrid (ndarray, optional) – Specific energy grid to map k energies to. Defaults to None.

  • lbins (ndarray, optional) – 1D array of L values to map to. Defaults to None.

  • jdir (str, optional) – Directory to find json files in. Defaults to None.

Returns:

A dictionary containing the calculated results.

Return type:

dict

Raises:

None –

kaipy.satcomp.scRCM.get_aspect(ax)

Calculate the aspect ratio of an axis.

Parameters:

ax – The axis object for which to calculate the aspect ratio.

Returns:

The aspect ratio of the axis.

kaipy.satcomp.scRCM.plt_ODF_Comp(AxSC, AxRCM, AxCB, odfData, mjd=None, cmapName='CMRmap', norm=None, forcePop=False)

Plot the ODF (Orientation Distribution Function) comparison between AxSC and AxRCM.

Parameters:

  • AxSC (matplotlib.axes.Axes) – The subplot for the SC (Spacecraft) ODF.

  • AxRCM (matplotlib.axes.Axes) – The subplot for the RCM (Remote Component Manipulator) ODF.

  • AxCB (matplotlib.axes.Axes) – The colorbar axis.

  • odfData (dict) – A dictionary containing the ODF data.

  • mjd (float) – The Modified Julian Date (MJD) to highlight on the plot (optional).

  • cmapName (str) – The name of the colormap to use (default: ‘CMRmap’).

  • norm (matplotlib.colors.Normalize) – The normalization object for the colorbar (optional).

  • forcePop (bool) – A flag indicating whether to force population of the subplots (default: False).

Returns:

None

kaipy.satcomp.scRCM.plt_rcm_eqlatlon(AxLatlon, AxEq, rcmData, satTrackData=None, AxCB=None, mjd=None, norm=None, cmapName='viridis')

Plot RCM data on equal latitude-longitude and equatorial coordinate systems.

Parameters:

  • AxLatlon (matplotlib.axes.Axes) – The axis object for the equal latitude-longitude plot.

  • AxEq (matplotlib.axes.Axes) – The axis object for the equatorial coordinate plot.

  • rcmData (dict) – A dictionary containing RCM data.

  • satTrackData (dict, optional) – A dictionary containing satellite track data. Default is None.

  • AxCB (matplotlib.axes.Axes, optional) – The colorbar axis object. Default is None.

  • mjd (float, optional) – The Modified Julian Date. Default is None.

  • norm (matplotlib.colors.Normalize, optional) – The normalization object for the color mapping. Default is None.

  • cmapName (str, optional) – The name of the colormap. Default is ‘viridis’.

Returns:

None

kaipy.satcomp.scRCM.plt_tl(AxTL, tkldata, AxCB=None, mjd=None, cmapName='CMRmap', norm=None)

Plot the total pressure as a function of L shell and time.

Parameters:

  • AxTL – The matplotlib Axes object for the L vs. Time plot.

  • tkldata – A dictionary containing the data for the plot.

  • AxCB – The matplotlib Axes object for the colorbar plot (optional).

  • mjd – The Modified Julian Date for a specific time point (optional).

  • cmapName – The name of the colormap to use (default: ‘CMRmap’).

  • norm – The normalization object for the color mapping (optional).

Returns:

None

kaipy.satcomp.scRCM.to_center(A)

kaipy.satcomp.scutils module

kaipy.satcomp.scutils.addFileToMerge(mergeH5, nextH5)

Add data from nextH5 file to mergeH5 file.

Parameters:

  • mergeH5 (h5py.File) – The HDF5 file to merge data into.

  • nextH5 (h5py.File) – The HDF5 file containing the data to be merged.

Returns:

None

kaipy.satcomp.scutils.addGAMERA(data, scDic, h5name)

Add GAMERA data to the given data dictionary.

Parameters:

  • data (dict) – The dictionary to which GAMERA data will be added.

  • scDic (dict) – Dictionary containing information about the spacecraft.

  • h5name (str) – The name of the HDF5 file containing the GAMERA data.

Returns:

None

kaipy.satcomp.scutils.addVar(mydata, scDic, varname, t0, t1, deltaT, epochStr='Epoch')

Add a variable to the given data dictionary.

Parameters:

  • mydata (dict) – The data dictionary to add the variable to.

  • scDic (dict) – The dictionary containing information about the variable.

  • varname (str) – The name of the variable.

  • t0 (float) – The start time of the data.

  • t1 (float) – The end time of the data.

  • deltaT (float) – The time step of the data.

  • epochStr (str, optional) – The name of the epoch variable. Defaults to ‘Epoch’.

Returns:

The status of the operation, including the HTTP status code.

Return type:

status (dict)

kaipy.satcomp.scutils.computeErrors(obs, pred)

Compute various error metrics between observed and predicted values.

Parameters: obs (array-like): Array of observed values. pred (array-like): Array of predicted values.

Returns: tuple: A tuple containing the following error metrics:

  • MAE (float): Mean Absolute Error.

  • MSE (float): Mean Squared Error.

  • RMSE (float): Root Mean Squared Error.

  • MAPE (float): Mean Absolute Percentage Error.

  • RSE (float): Relative Squared Error.

  • PE (float): Prediction Efficiency.

kaipy.satcomp.scutils.convertGameraVec(x, y, z, ut, fromSys, fromType, toSys, toType)

Convert a vector from one coordinate system to another.

Parameters:

  • x (float) – The x-coordinate of the vector.

  • y (float) – The y-coordinate of the vector.

  • z (float) – The z-coordinate of the vector.

  • ut (float) – The universal time of the vector.

  • fromSys (str) – The source coordinate system.

  • fromType (str) – The source coordinate type.

  • toSys (str) – The target coordinate system.

  • toType (str) – The target coordinate type.

Returns:

The converted vector.

Return type:

outvec

kaipy.satcomp.scutils.copy_attributes(in_object, out_object)

Copy attributes between 2 HDF5 objects.

Parameters:

  • in_object – The source HDF5 object from which attributes will be copied.

  • out_object – The destination HDF5 object to which attributes will be copied.

Returns:

None

kaipy.satcomp.scutils.createInputFiles(data, scDic, scId, mjd0, sec0, fdir, ftag, numSegments)

Create input files for satellite interpolation using sctrack.

Parameters:

  • data (dict) – Dictionary containing the data.

  • scDic (dict) – Dictionary containing satellite information.

  • scId (str) – Satellite ID.

  • mjd0 (float) – Modified Julian Date.

  • sec0 (float) – Seconds.

  • fdir (str) – Directory path.

  • ftag (str) – File tag.

  • numSegments (int) – Number of segments.

Returns:

A tuple containing the paths of the created files and the conversion factor.

Return type:

tuple

Raises:

None –

kaipy.satcomp.scutils.createMergeFile(fIn, fOut)

Creates a merged HDF5 file by copying datasets and attributes from the input file to the output file.

Parameters:

  • fIn (str) – Path to the input HDF5 file.

  • fOut (str) – Path to the output HDF5 file.

Returns:

The output HDF5 file object.

Return type:

h5py.File

Raises:

IOError – If there is an error reading the input file.

kaipy.satcomp.scutils.create_sctrack_helio_input_files(data, scDic, scId, mjd0, sec0, gamhelio_results_directory, ftag, numSegments, mjdc)
kaipy.satcomp.scutils.create_sctrack_helio_trajectory_file(sc_data, sc_metadata, sc_id, mjd0, sec0, gamhelio_results_directory, ftag, numSegments, mjdc)

Create the input trajectory file needed by the sctrack.x interpolator.

Parameters:

  • sc_data (dict) – Dictionary containing the spacecraft data.

  • sc_metadata (dict) – Dictionary containing the spacecraft metadata.

  • sc_id (str) – Identifier for the spacecraft.

  • mjd0 (float) – Modified Julian Date (MJD) at the start of the simulation.

  • sec0 (float) – Seconds at the start of the simulation.

  • gamhelio_results_directory (str) – Path to the directory where the gamhelio results are stored.

  • ftag (str) – File tag.

  • numSegments (int) – Number of segments.

  • mjdc (float) – Modified Julian Date (MJD) at the current time.

Returns:

Path to the trajectory file.

Return type:

str

kaipy.satcomp.scutils.create_sctrack_helio_xml(output_directory, run_id, spacecraft_id, trajectory_file, num_parallel_segments=1)

Generate heliosphere XML input file for sctrack.x.

Parameters:

  • output_directory (str) – Path to directory containing gamhelio model output.

  • run_id (str) – Identifying tag used in gamhelio result filenames.

  • spacecraft_id (str) – Name string (no spaces allowed) for spacecraft used in trajectory.

  • trajectory_file (str) – Name of file containing spacecraft trajectory.

  • num_parallel_segments (int, optional) – Number of threads for sctrack.x to use. Defaults to 1.

Returns:

Root document object for XML.

Return type:

minidom.Document

kaipy.satcomp.scutils.errorReport(errorName, scId, data)

Writes error report to a file.

Parameters:

  • errorName (str) – The name of the error file.

  • scId (int) – The ID of the spacecraft.

  • data (dict) – A dictionary containing the data.

Returns:

None

kaipy.satcomp.scutils.extractGAMERA(data, scDic, scId, mjd0, sec0, fdir, ftag, cmd, numSegments, keep)

Extracts GAMERA data.

Parameters:

  • data (type) – Description of the data argument.

  • scDic (type) – Description of the scDic argument.

  • scId (type) – Description of the scId argument.

  • mjd0 (type) – Description of the mjd0 argument.

  • sec0 (type) – Description of the sec0 argument.

  • fdir (type) – Description of the fdir argument.

  • ftag (type) – Description of the ftag argument.

  • cmd (type) – Description of the cmd argument.

  • numSegments (type) – Description of the numSegments argument.

  • keep (type) – Description of the keep argument.

Returns:

Description of the return value.

Return type:

type

Raises:

Exception – Description of the exception(s) that can be raised.

kaipy.satcomp.scutils.genSCXML(fdir, ftag, scid='sctrack_A', h5traj='sctrack_A.h5', numSegments=1)

Generate an SCXML document for Kaiju simulation.

Parameters:

  • fdir (str) – The directory of the simulation files.

  • ftag (str) – The tag of the simulation file.

  • scid (str, optional) – The ID of the simulation. Defaults to “sctrack_A”.

  • h5traj (str, optional) – The name of the H5 trajectory file. Defaults to “sctrack_A.h5”.

  • numSegments (int, optional) – The number of segments. Defaults to 1.

Returns:

The SCXML document.

Return type:

xml.dom.minidom.Document

kaipy.satcomp.scutils.genSatCompLockScript(scId, fdir, account='P28100045')

Generate a lock script for satellite computation.

Parameters: - scId (str): The ID of the satellite computation. - fdir (str): The directory where the lock script will be created. - account (str): The account to be used for the job. Default is ‘P28100045’.

Returns: - pbsFileName (str): The path to the created lock script file.

kaipy.satcomp.scutils.genSatCompPbsScript(scId, fdir, cmd, account='P28100045')

Generate a PBS script for satellite data processing.

Parameters:

  • scId (str) – The identifier for the satellite data.

  • fdir (str) – The directory where the script and data files are located.

  • cmd (str) – The command to run for the analysis.

  • account (str, optional) – The account to use for the PBS job. Defaults to ‘P28100045’.

Returns:

The filename of the generated PBS script.

Return type:

str

kaipy.satcomp.scutils.getCdasDsetInterval(dsName)

Retrieves the start and end time of a dataset with the given name.

Parameters:

dsName (str) – The name of the dataset.

Returns:

The start time of the dataset. end (str): The end time of the dataset.

Return type:

start (str)

kaipy.satcomp.scutils.getJScl(Bmag, Beq, en=2.0)

Calculate the fraction based on accessible Alpha given sin^n(alpha) dependence on intensity.

Parameters:

  • Bmag (array-like) – Array of magnetic field magnitudes.

  • Beq (array-like) – Array of equivalent magnetic field magnitudes.

  • en (float, optional) – Exponent value for sin^n(alpha). Default is 2.0.

Returns:

Array of calculated fractions based on accessible Alpha.

Return type:

It (array-like)

kaipy.satcomp.scutils.getSatData(scDic: dict, t0: str, t1: str, deltaT: float)

Fetch spacecraft data in the specified time range.

Fetch spacecraft data for the specified time range, at the specified cadence.

Parameters:

  • scDic (dict) – Spacecraft descriptive information.

  • t0 (str) – Start time for data, in format “%Y-%m-%dT%H:%M:%SZ”.

  • t1 (str) – Stop time for data, in format “%Y-%m-%dT%H:%M:%SZ”.

  • deltaT (float) – Cadence for requested spacecraft data (seconds).

Returns:

Query status returned by CDAWeb. mydata (spacepy.datamodel.SpaceData): All of the spacecraft for the specified time range and cadence.

Return type:

status (dict)

kaipy.satcomp.scutils.getScIds(spacecraft_data_file: str = PosixPath('/home/docs/checkouts/readthedocs.org/user_builds/kaipy-docs/envs/latest/lib/python3.12/site-packages/kaipy/satcomp/sc_cdasws_strs.json'), doPrint: bool = False)
kaipy.satcomp.scutils.getWeights_ConsArea(og, og_lower, og_upper, ng, ng_lower, ng_upper)

Calculate overlap (weights) to map values on one grid to another, where total width in grid dimension are conserved (i.e. properly map RCM eetas to uniform grid)

Parameters:

  • og (list) – Old grid.

  • og_lower (list) – Lower bounds of each grid point in the old grid.

  • og_upper (list) – Upper bounds of each grid point in the old grid.

  • ng (list) – New grid.

  • ng_lower (list) – Lower bounds of each grid point in the new grid.

  • ng_upper (list) – Upper bounds of each grid point in the new grid.

Returns:

A list of lists representing the weight map. Each element in the outer list corresponds to a cell center on the new grid. Each inner list contains pairs of indices and fractions representing the overlap between the new grid cell and the old grid cells.

Return type:

list

Example

og: || | | | | | | | ng: | | | | | | | | | | | For each cell center on ng, calculate which og cells overlap and the fraction of overlap.

kaipy.satcomp.scutils.get_helio_cdaweb_data(sc_id, sc_metadata, start_time, end_time, cdaweb_data_interval, verbose=False, debug=False)

Fetch heliosphere spacecraft data in the specified time range.

Fetch heliosphere spacecraft data for the specified time range, at the specified cadence. This function copies the raw CDAWeb data from the query result object into a local data object. The raw data must then be ingested to convert it to a form that gamhelio understands.

Parameters:

  • sc_id (str) – ID string for spacecraft.

  • sc_metadata (dict) – Spacecraft descriptive information for the heliosphere spacecraft YML file.

  • start_time (str) – Start time for data, in format “%Y-%m-%dT%H:%M:%SZ”.

  • end_time (str) – Stop time for data, in format “%Y-%m-%dT%H:%M:%SZ”.

  • cdaweb_data_interval (float) – Cadence for requested spacecraft data (seconds).

  • verbose (bool, optional) – Set to True for printing verbose progress messages. Defaults to False.

  • debug (bool, optional) – Set to True for printing debugging messages. Defaults to False.

Returns:

All of the spacecraft for the specified time range and cadence.

Return type:

spacepy.datamodel.SpaceData

Raises:

None –

kaipy.satcomp.scutils.helio_addVar(my_data, scDic, varname, t0, t1, deltaT, epochStr='Epoch')

Adds a variable to the my_data dictionary by pulling data from the CDAWeb dataset.

Parameters:

  • my_data (dict) – The dictionary to which the variable will be added.

  • scDic (dict) – A dictionary containing information about the CDAWeb dataset and variable.

  • varname (str) – The name of the variable to be added.

  • t0 (str) – The start time of the data retrieval period.

  • t1 (str) – The end time of the data retrieval period.

  • deltaT (str) – The time interval between data points.

  • epochStr (str, optional) – The name of the epoch attribute in the data. Defaults to “Epoch”.

Returns:

The status of the data retrieval operation.

Return type:

dict

kaipy.satcomp.scutils.helio_pullVar(cdaObsId, cdaDataId, t0, t1, deltaT=60, epochStr='Epoch', doVerbose=False)

Pull spacecraft data from CDAWeb.

Pull spacecraft data from CDAWeb.

Parameters:

  • cdaObsId (str) – Dataset name.

  • cdaDataId (str or list of str) – Desired variable(s) from dataset.

  • t0 (str) – Data start time, formatted as ‘%Y-%m-%dT%H:%M:%S.%f’.

  • t1 (str) – Data end time, formatted as ‘%Y-%m-%dT%H:%M:%S.%f’.

  • deltaT (float, optional) – Time cadence (seconds), used when interpolating through time with no data. Defaults to 60.

  • epochStr (str, optional) – Name of time variable in dataset. Defaults to “Epoch”.

  • doVerbose (bool, optional) – Helpful for debugging/diagnostics. Defaults to False.

Returns:

Status information returned for the query. data (spacepy.pycdf.CDFCopy): Object containing data returned by the query, None if no results.

Return type:

status (dict)

kaipy.satcomp.scutils.ingest_cdaweb_density(sc_data, sc_metadata, MJDc, verbose=False, debug=False)

Convert CDAWeb density to gamhelio format.

Convert CDAWeb density to gamhelio format.

Parameters:

  • sc_data (dm.SpaceData) – SpaceData object for all data as originally returned from CDAWeb.

  • sc_metadata (dict) – Spacecraft descriptive information for the heliosphere spacecraft YML file.

  • MJDc (float) – Value of MJDc attribute from gamhelio result files.

  • verbose (bool, optional) – Set to True for printing verbose progress messages. Defaults to False.

  • debug (bool, optional) – Set to True for printing debugging messages. Defaults to False.

Returns:

None

kaipy.satcomp.scutils.ingest_cdaweb_ephemeris(sc_data, sc_metadata, MJDc, verbose=False, debug=False)

Convert CDAWeb spacecraft ephemeris to gamhelio format.

Parameters:

  • sc_data (dm.SpaceData) – SpaceData object for all data as originally returned from CDAWeb.

  • sc_metadata (dict) – Spacecraft descriptive information for the heliosphere spacecraft YML file.

  • MJDc (float) – Value of MJDc attribute from gamhelio result files.

  • verbose (bool, optional) – Set to True for printing verbose progress messages. Defaults to False.

  • debug (bool, optional) – Set to True for printing debugging messages. Defaults to False.

Returns:

None

kaipy.satcomp.scutils.ingest_cdaweb_magnetic_field(sc_data, sc_metadata, MJDc, verbose=False, debug=False)

Convert CDAWeb magnetic field to gamhelio format.

Converts the CDAWeb magnetic field to the gamhelio format. If necessary, it computes the radial component of the magnetic field in the GH(MJDc) frame.

Parameters:

  • sc_data (dm.SpaceData) – SpaceData object for all data as originally returned from CDAWeb.

  • sc_metadata (dict) – Spacecraft descriptive information for the heliosphere spacecraft YML file.

  • MJDc (float) – Value of MJDc attribute from gamhelio result files.

  • verbose (bool, optional) – Set to True for printing verbose progress messages. Defaults to False.

  • debug (bool, optional) – Set to True for printing debugging messages. Defaults to False.

Returns:

None

kaipy.satcomp.scutils.ingest_cdaweb_speed(sc_data, sc_metadata, MJDc, verbose=False, debug=False)

Convert CDAWeb speed to gamhelio format.

Convert CDAWeb speed to gamhelio format. If needed, compute the radial component of the speed in the GH(MJDc) frame.

Parameters:

  • sc_data (dm.SpaceData) – SpaceData object for all data as originally returned from CDAWeb.

  • sc_metadata (dict) – Spacecraft descriptive information for the heliosphere spacecraft YML file.

  • MJDc (float) – Value of MJDc attribute from gamhelio result files.

  • verbose (bool, optional) – Set to True for printing verbose progress messages. Defaults to False.

  • debug (bool, optional) – Set to True for printing debugging messages. Defaults to False.

Returns:

None

kaipy.satcomp.scutils.ingest_cdaweb_temperature(sc_data, sc_metadata, MJDc, verbose=False, debug=False)
kaipy.satcomp.scutils.ingest_helio_cdaweb_data(sc_id, sc_data, sc_metadata, MJDc, verbose=False, debug=False)

Ingest CDAWeb data to gamhelio format.

Convert CDAWeb data to gamhelio format.

Parameters:

  • sc_data (dm.SpaceData) – SpaceData object for all data as originally returned from CDAWeb.

  • sc_metadata (dict) – Spacecraft descriptive information for the heliosphere spacecraft YML file.

  • MJDc (float) – Value of MJDc attribute from gamhelio result files.

  • verbose (bool, optional) – Set to True for printing verbose progress messages. Defaults to False.

  • debug (bool, optional) – Set to True for printing debugging messages. Defaults to False.

Returns:

None

kaipy.satcomp.scutils.ingest_interpolated_inDomain(h5file, sc_data)

Ingest the interpolated inDomain flag.

This function ingests the interpolated inDomain flag from the given h5file and updates the sc_data dictionary with the ingested data.

Parameters:

  • h5file (h5py.File) – The HDF5 file containing the inDomain flag.

  • sc_data (dict) – The dictionary to update with the ingested data.

Returns:

None

Raises:

None –

kaipy.satcomp.scutils.ingest_interpolated_number_density(h5file, sc_data)

Ingest the interpolated number density and transform as needed.

Parameters:

  • h5file (h5py.File) – The HDF5 file object containing the interpolated number density.

  • sc_data (dict) – The dictionary to store the interpolated number density.

Returns:

None

Raises:

None –

kaipy.satcomp.scutils.ingest_interpolated_radial_magnetic_field(h5file, sc_data)

Ingest the interpolated radial magnetic field and transform as needed.

This function ingests the interpolated radial magnetic field from an HDF5 file and performs necessary transformations. The radial magnetic field is computed in the GH(MJDc) frame and then transformed to the GSE(t) frame.

Parameters:

  • h5file (h5py.File) – The HDF5 file containing the interpolated magnetic field data.

  • sc_data (dict) – The dictionary to store the ingested data.

Returns:

None

Raises:

None –

kaipy.satcomp.scutils.ingest_interpolated_radial_velocity(h5file, sc_data)

Ingest the interpolated radial velocity and transform as needed.

This function takes in an HDF5 file h5file and a dictionary sc_data, and ingests the interpolated radial velocity from the HDF5 file. It then transforms the velocity as needed and adds it to the sc_data dictionary.

Parameters:

  • h5file (h5py.File) – The HDF5 file containing the interpolated radial velocity data.

  • sc_data (dict) – The dictionary to which the interpolated radial velocity will be added.

Return type:

None

Raises:

None –

kaipy.satcomp.scutils.ingest_interpolated_temperature(h5file, sc_data)

Ingest the interpolated temperature and transform as needed.

Parameters:

  • h5file (h5py.File) – The HDF5 file containing the interpolated model pressure and density.

  • sc_data (dict) – The dictionary to which the computed gamhelio temperature will be added.

Returns:

None

Raises:

None –

kaipy.satcomp.scutils.ingest_interpolated_variables(sc_data, sc_metadata, interpolated_results_path)

Copy the interpolated model results and transform as needed.

Copy the variables in the input HDF5 file into new variables in the HDF5 file with GAMERA_-prefixed descriptive names, and more metadata.

Convert vector values from the gamhelio frame (GH(t0)) to the frame of the spacecraft.

Parameters:

  • sc_data (spacepy.datamodel.SpaceData) – All of the spacecraft and interpolated model results so far.

  • sc_metadata (dict) – Spacecraft descriptive information.

  • interpolated_results_path (str) – Path to HDF5 file containing gamhelio model results interpolated to the spacecraft positions, all in the GH(t0) frame.

Returns:

None

Raises:

TypeError – If target frame is not GSE.

kaipy.satcomp.scutils.interpolate_gamhelio_results_to_trajectory(sc_data, sc_metadata, sc_id, first_MJD, first_elapsed_seconds, gamhelio_results_directory, run_id, sctrack_cmd, num_segments, keep, MJDc)

Interpolate gamhelio data to the spacecraft trajectory.

Interpolate gamhelio data to the spacecraft trajectory. This code assumes T, X, Y, Z are already in the GH(MJDc) frame.

Parameters:

XXX

Returns:

None

Raises:

XXX –

kaipy.satcomp.scutils.matchUnits(data)

Check if the units of specific variables in the given data match the expected units. If the units do not match, perform unit conversions or print warning messages.

Parameters:

data (dict) – A dictionary containing the data variables.

Returns:

None

kaipy.satcomp.scutils.mergeFiles(scId, fdir, numSegments)

Merge multiple files into a single file.

Parameters:

  • scId (str) – The identifier of the file.

  • fdir (str) – The directory where the files are located.

  • numSegments (int) – The number of segments to merge.

Returns:

The path of the merged file.

Return type:

str

kaipy.satcomp.scutils.pullVar(cdaObsId: str, cdaDataId, t0: str, t1: str, deltaT: float = 60, epochStr: str = 'Epoch', doVerbose: bool = False)

Pull spacecraft data from CDAWeb.

Pulls spacecraft data from CDAWeb.

Parameters:

  • cdaObsId (str) – Dataset name.

  • cdaDataId (str or list of str) – Desired variable(s) from dataset.

  • t0 (str) – Data start time, formatted as ‘%Y-%m-%dT%H:%M:%S.%f’.

  • t1 (str) – Data end time, formatted as ‘%Y-%m-%dT%H:%M:%S.%f’.

  • deltaT (float, optional) – Time cadence (seconds), used when interpolating through time with no data. Defaults to 60.

  • epochStr (str, optional) – Name of time variable in dataset. Defaults to “Epoch”.

  • doVerbose (bool, optional) – Helpful for debugging/diagnostics. Defaults to False.

Returns:

Status information returned for the query. spacepy.pycdf.CDFCopy: Object containing data returned by the query, None if no results.

Return type:

dict

kaipy.satcomp.scutils.read_MJDc(path)

Read the MJD of the center of the WSA input map.

Read the MJD of the center of the WSA input map. This value was originally read from the FITS file used to provide the WSA initial conditions for a gamhelio run. It is now stored as a global attribute in all of the HDF5- format files generated by gamhelio. This MJD value should be used as the date for constructing the gamhelio coordinate frame, needed to convert values from CDAWeb to gamhelio coordinates.

Parameters:

path (str) – Path to HDF5 results file from gamhelio.

Returns:

Value of MJDc global attribute.

Return type:

float

kaipy.satcomp.scutils.trilinterp(xbnd, ybnd, zbnd, valbnd, x, y, z)

3D linear interpolation

Interpolates a variable in a 3D space using linear interpolation.

Parameters:

  • xbnd (list) – A list of two elements representing the bounding values of the x dimension.

  • ybnd (list) – A list of two elements representing the bounding values of the y dimension.

  • zbnd (list) – A list of two elements representing the bounding values of the z dimension.

  • valbnd (ndarray) – A 2x2x2 numpy array of the variable to be interpolated.

  • x (float) – The x coordinate of the point inside the bounds.

  • y (float) – The y coordinate of the point inside the bounds.

  • z (float) – The z coordinate of the point inside the bounds.

Returns:

The interpolated value at the given point.

Return type:

float

kaipy.satcomp.scutils.varMap_1D(og, ng, var)

Map variable from one grid to another.

Parameters:

  • og (array-like) – The old grid.

  • ng (array-like) – The new grid.

  • var (array-like) – The variable to re-map.

Returns:

The re-mapped variable.

Return type:

array-like

kaipy.satcomp.scutils.write_helio_error_report(error_file_path, sc_id, sc_data)

Save an error report for the current data.

Compute and save an error report for the current data.

Parameters:

  • errorName (str) – Path to file to hold error report.

  • scId (str) – ID string for spacecraft.

  • data (spacepy.datamodel.SpaceData) – The current spacecraft and model data.

Returns:

None

kaipy.satcomp.scutils.xyz_to_L(x, y, z)

Convert Cartesian coordinates (x, y, z) to L-shell value.

Converts spacecraft Cartesian coordinates to L-shell value assuming a perfect dipole. :param x: The x-coordinate. :type x: float :param y: The y-coordinate. :type y: float :param z: The z-coordinate. :type z: float

Returns:

The L-shell value.

Return type:

float