Module Documentation¶

This page documents the classes available in the pyCactus module.

CactusRun¶

class pyCactus.CactusRun(run_directory, case_name, input_fname='', geom_fname='', load_field_output=True, load_wakeelem_output=True, load_probe_output=True, wakeelem_fnames_pattern='*WakeElemData_*.csv', field_fnames_pattern='*FieldData_*.csv', probe_fnames_pattern='probe_*.csv*', quiet=False)[source]¶

Class for interrogating a CACTUS input deck.

input¶: CactusInput class – Input file class.

geom¶: CactusGeom class – Geometry data class.

param_data¶: Pandas DataFrame – Parameter data.

rev_data¶: Pandas DataFrame – Revolution-averaged data.

time_data¶: Pandas DataFrame – Time data.

bladeelem_data¶: CactusBladeElem class – Blade element data.

wakeelems¶: CactusWakeElems class – Wake element data class.

field¶: CactusField class – Field data class.

probes¶: CactusProbes class. – Probe class.

nti¶: int – Number of timesteps per iteration.

tsr¶: float – Tip speed ratio (non-dimensional).

dt¶: float – Normalized timestep length (non-dimensional).

input_fname¶: str – Input data filename.

geom_fname¶: str – Geometry data filename.

param_fname¶: str – Parameter data filename.

rev_fname¶: str – Revolution-averaged data filename.

elem_fname¶: str – Blade element data filename.

time_fname¶: str – Time data filename.

wake_filenames¶: list – List of filenames containing wake element data.

field_filenames¶: list – List of filenames containing field data.

probe_filenames¶: list – List of filenames containing probe data.

__init__(run_directory, case_name, input_fname='', geom_fname='', load_field_output=True, load_wakeelem_output=True, load_probe_output=True, wakeelem_fnames_pattern='*WakeElemData_*.csv', field_fnames_pattern='*FieldData_*.csv', probe_fnames_pattern='probe_*.csv*', quiet=False)[source]¶

Initialize the class, reading some data to memory.

This method relies on recursive searches within the specified run directory to find the appropriate CACTUS output files. Therefore, each run directory should only contain one set of output files (or else the behavior cannot be guaranteed).

Parameters:

run_directory (str) – Path to the directory containing the CACTUS run.
case_name (str) – ‘case name’ which precedes all input and output files.
input_fname (Optional[str]) – Input filename (default ./[case_name].in).
geom_fname (Optional[str]) – Geometry filename (default ./[case_name].geom)
load_field_output (bool) – True (default) to load field data, False otherwise.
load_wakeelem_output (bool) – True (default) to load wake element data, False otherwise.
load_probe_output (bool) – True (default) to load probe data, False otherwise.
wakeelem_fnames_pattern (Optional[str]) – Glob pattern for wake element data filenames (default is *WakeElemData_*.csv)
field_fnames_pattern (Optional[str]) – Glob pattern for field data filenames (default is *FieldData_*.csv)
probe_fnames_pattern (Optional[str]) – Glob pattern for probe filenames (default is probe_*.csv)
quiet (Optional[bool]) – Set True to hide print statements (default is False).

__weakref__¶: list of weak references to the object (if defined)

dt¶: The simulation timestep (non-dimensional).

nti¶

Simulation nti parameter (timesteps per iteration).

Extracted from the input namelist file.

period¶: The simulation time for one revolution period (non-dimensional).

rev_to_time(rev)[source]¶: Compute the normalized time from a revolution.

rev_to_timestep(rev)[source]¶: Compute the normalized time from a fractional revolution.

rotor_data_at_time_index(time_index)[source]¶

Extract a single time instance from the time dataframe.

Returns the time corresponding to the given time_index, and a dataframe containing the appropriate subset of data.

Parameters:	time_index (int) – An integer of the time_index
Returns:	time (float) – The time corresponding to the given time index df (pandas.DataFrame) – The dataframe containing the time data at that particular instance.

time_to_rev(time)[source]¶: Compute the fractional revolution from a normalized time.

tsr¶: Simulation tsr parameter (tip speed ratio).

CactusBladeElem¶

class pyCactus.CactusBladeElem(filename)[source]¶

Class to manage CACTUS blade element data.

data¶: Pandas dataframe – Raw blade element data.

filename¶: str – Path to raw blade element data file.

__init__(filename)[source]¶: Initialize class, read in data.

__weakref__¶: list of weak references to the object (if defined)

data_at_time_index(time_index)[source]¶

Get blade data a specified time.

Extract a subset dataframe of the “Element Data” dataframe by time index. Returns the time corresponding to the given time_index, and a list of dataframes containing the data, with one dataframe per blade.

Parameters:	time_index (int) – The time index.
Returns:	time (float) – The non-dimensionalized time. dfs_blade (list) – A list of dataframes, each holding blade data.

data_time_average(qty_name, timesteps, blade_num)[source]¶

Compute a time-averaged a blade quantity distribution.

Compute a time-averaged blade quantity distribution over a number of timesteps. This may be used to, for example, compute the revolution- averaged blade quantities, such as circulation distribution, angle of attack, and local blade relative velocity.

Parameters:	qty_name (str) – The column name for the desired blade quantity. timesteps (list) – List of timesteps (integer). blade_num (int) – Index of the blade number, indexed from 0).
Returns:	qty_avg – The array of averaged blade data.
Return type:	numpy.array

CactusWakeElems¶

class pyCactus.CactusWakeElems(filenames, read_headers=True)[source]¶

Class for manipulating wake element data from CACTUS.

filenames¶: list – Filenames (str) of wake element data files.

num_times¶: int – Number of timesteps of wake element data.

times¶: list – List of times (float) of wake element data.

fdict¶: dict – A dictionary of {time : fname}.

__init__(filenames, read_headers=True)[source]¶: Initializes the instance.

__weakref__¶: list of weak references to the object (if defined)

get_df_inst(time=None, fname=None)[source]¶

Gets the data from a specified time or filename.

Either the time or the filename must be specified.

Parameters:	time (Optional[float]) – The time at which to extract the dataframe. fname (Optional[str]) – The filename to read (defaults to self.fdict[time]).
Returns:	df_inst – DataFrame of the time.
Return type:	pandas.DataFrame

read_file_headers()[source]¶

Gets the times from the headers of each data file in the instance filenames attribute amd stores to instance variables self.times and self.fdict

Returns:	times (list) – List of times (float) of wake element data. fdict (dict) – A dictionary of {time : fname}.

wakedata_from_df(df)[source]¶

Takes a dataframe containing wake node data at a single timestep and returns a dictionary of the data as np.arrays.

NumPy arrays are keyed by a descriptive variable name.

Parameters:	df (pandas.DataFrame) –
Returns:	data_arrays (dict) – Dictionary of np.arrays containing the data. has_node_ids (bool) – True if wake element data has ‘Node ID’ column, False if not.

write_vtk_series(path, name, id_flag=False, num_blade_elems=[], print_status=True)[source]¶

Writes the wake element data to a time series of VTK files

Data is written as VTK unstructured data (.vtu). ID data is a scalar (integer). Velocity data is a vector.

Also writes a Paraview collection file (.pvd) which contains the normalized times of each timestep.

Parameters:

path (str) – The path to which to write the VTK files.
name (str) – The prefix of the VTK filenames.
id_flag (Optional[bool]) – If True, each particle is assigned a unique ID so that it can be tracked. If the data contains a node_ids column already, then these will be written to the VTK file regardless of id_flag.
num_blade_elems (Optional[list]) – The number of elements for each blade.
print_status (bool) – True to print the status of VTK conversion, False to suppress.

Returns:

data_filenames (list) – List of the VTK filenames.
pvd_filename (str) – .pvd collection filename.

CactusField¶

class pyCactus.CactusField(filenames, read_headers=True, read_grid_dims=True)[source]¶

Class for reading WakeData (element) from CSV files.

Grid node locations X,Y,Z are assumed to be the same for all timesteps.

filenames¶: list – Filenames (str) of wake element data files.

num_times¶: int – Number of timesteps of wake element data.

times¶: list – List of times (float) of wake element data.

fdict¶: dict – A dictionary of {time : filename}.

grid_dims¶: dict – A dictionary of grid dimensions.

__init__(filenames, read_headers=True, read_grid_dims=True)[source]¶: Initialize the instance.

__weakref__¶: list of weak references to the object (if defined)

field_time_average(ti_start=-5, ti_end=-1)[source]¶

Return the time-averaged field data over a specified timestep range.

Averaging is done over the time range self.times[ti_start:ti_end].

Parameters:	ti_start (Optional[int]) – The timestep index to start averaging (default -5) ti_end (Optional[int]) – The timestep index to end averaging (default -1)
Returns:	data_dict_mean – A dictionary of grid coordinates and time-averaged data.
Return type:	dict

fielddata_from_df(df)[source]¶

Return the dictionary containing fielddata variarbles.

Take a dataframe containing field data at a single timestep, returns a dictionary of the data as np.arrays. Dicttionary is keyed by a descriptive variable name.

Parameters:	df (pandas.DataFrame) –
Returns:	grid_data (dict) – Dictionary of np.arrays containing the data. grid_dims (dict) – Dictionary of grid dimensions.

get_df_inst(time=None, fname=None)[source]¶

Get the data from a specified time or filename.

Either the time or the filename must be specified.

Parameters:	time (Optional[float]) – The time at which to extract the dataframe. fname (Optional[str]) – The filename to read (defaults to self.fdict[time]).
Returns:	df_inst – DataFrame of the time.
Return type:	pandas.DataFrame

pointdata_time_series(p_list, ti_start=0, ti_end=-1)[source]¶

Extract a time series of data at a single point or points.

Loops through the time data to extract a time series of data at a specified point or points. Uses nearest-point to avoid interpolation.

Parameters:

p_list (list) – List of points, where each point is a tuple of length 3.
ti_start (Optional[int]) – The timestep index to start (default 0).
ti_end (Optional[int]) – The timestep index to end (default -1)

Returns:

data_dict (dict) – Dictionary of the time series velocity data:

't'   : times
'u'   : x-velocity
'v'   : y-velocity
'w'   : z-velocity
'ufs' : freestream x-velocity
'vfs' : freestream y-velocity
'wfs' : freestream z-velocity

p_nearest (list) – List of the nearest points to those in p_list (points at which data was returned).

read_file_headers()[source]¶

Read the file headers, store times to instance variable.

Gets the times from the headers of each data file in the instance filenames attribute amd stores to instance variables self.times and self.fdict

Returns:	times (list) – List of times (float) of wake element data. fdict (dict) – A dictionary of {time : fname}.

read_grid_dims(filename)[source]¶

Read the grid dimensions of a file.

Returns:	grid_dims – Dictionary of grid dimension.
Return type:	dict

write_vtk_series(path, name, print_status=True)[source]¶

Write the field data to a time series of VTK files.

Data is written as VTK structured data (.vts). Velocity data is a vector field.

Also writes a Paraview collection file (.pvd) which contains the normalized times of each timestep.

Parameters:

path (str) – The path to which to write the VTK files.
name (str) – The prefix of the VTK filenames.
print_status (bool) – True to print the status of VTK conversion, False to suppress.

Returns:

data_filenames (list) – List of the VTK filenames.
pvd_filename (str) – .pvd collection filename.

CactusGeom¶

class pyCactus.CactusGeom(geom_filename)[source]¶

Class for parsing CACTUS geometry data.

globalvars¶: dict – Global variables from geometry file.

blades¶: list – List of dicts of blade geometry variables.

struts¶: list – List of dicts of strut geometry variables.

__init__(geom_filename)[source]¶: Initializes the class, reads in geometry data to class attributes.

__weakref__¶: list of weak references to the object (if defined)

distance_to_rotation_axis(p, n, a)[source]¶

Computes the distance between a point and a rotation axis.

http://en.wikipedia.org/wiki/Distance_from_a_point_to_a_line#Vector_formulation

Parameters:	p (numpy.array) – The coordinates of the point. n (numpy.array) – Vector of the rotation axis. a (numpy.array) – Coincident point of the rotation axis.

read_geom(filename, blade_num_lines=24, strut_num_lines=18)[source]¶

Reads data from a CACTUS .geom file.

Parameters:

filename (str) – The geometry filename.
blade_num_lines (int) – Number of lines of data per blade.
strut_num_lines (int) – Number of lines of data per strut.

Returns:

globalvars (dict) – Global variables from geometry file.
blade (list) – List of dicts of blade geometry variables.
strut (list) – List of dicts of strut geometry variables.

CactusProbes¶

class pyCactus.CactusProbes(filenames)[source]¶

Probes class for CACTUS probe data.

locations¶: dict – Dictionary of {id (int) : prob_location (numpy.array)}

filenames¶: dict – Dictionary of {id (int) : prob_filename (str)}

__init__(filenames)[source]¶: Initializes Probes class.

__weakref__¶: list of weak references to the object (if defined)

get_probe_data_by_id(id)[source]¶

Returns a Pandas dataframe of the probe data with given id.

Parameters:	id (int) – ID of the probe we wish to get data from.
Returns:	df – DataFrame of the probe data.
Return type:	pandas.DataFrame

num_probes¶: The number of probes.

plot_probe_data_by_id(id, ax=None, timestep=False, plot_fs=False)[source]¶

Plots the velocity vs. time for a specific probe.

Parameters:

id (int) – Probe ID to plot
ax (matplotlib axis) – Axis on which to plot series. If not specified, creates a new figure.
timestep (Optional[bool]) – True to plot x-axis as timestep instead of normalized time (default False).
plot_fs (Optional[bool]) – True to plot freestream velocities in addition to induced velocities (default False)

Returns:

figure (matplotlib.figure.Figure) – Figure handle.
ax (matplotlib.axes._subplots.AxesSubplot) – Axis handle.

read_probe_files(filenames)[source]¶

Find probe files in run directory and read the headers.

Searches within the specified run directory to find files matching the pattern *probe*.csv. Reads in the header data to class attributes.

Parameters:	filenames (list) – List of probe filenames to read in