adamspy.adripy package

Submodules

adamspy.adripy.constants module

Contains some constant values used through out the adripy package.

adamspy.adripy.constants.TO_PARAMETER_PATTERN

Regular expression used to find a parameter definition line in a tiem orbit file

Type:SRE_Pattern

adamspy.adripy.constants.TO_LENGTH_PARAM

Defines for each type of Adams Drill tool what tiem orbit parameter to use to get the length of the tool.

Type:dict

adamspy.adripy.constants.ADRILL_IDS

Defines the spline id and the variable id for wob, rpm, rop, and gpm in an Adams Drill dataset (.adm) file.

Type:dict of dict

adamspy.adripy.constants.DATABASE_INFO

Defines the structure of an Adams Drill database (.cdb).

Type:dict of dict

adamspy.adripy.database module

Tools for working with Adams Drill Databases

adamspy.adripy.database.fix_strings_in_cdb(cdb_path, old_cdb_path=None, cdb_name=None)

Finds all the string files in the Adams Drill Database given in cdb_path and converts all cdb references in the string files to cdb notation. If old_cdb_path and cdb_name are given, replaces any references to old_cdb_path with references to cdb_name using cdb notation.

Parameters:

• cdb_path (str) – Path to an Adams Drill Database
• old_cdb_path (str) – Filepath to a cdb which should be replaced. (default is None)
• cdb_name (str) – Name of the cdb with which to replace the old file path. (default is None)

adamspy.adripy.database.replace_old_cdb_paths_in_string(string_file, old_cdb_path, cdb_name)

Replaces all occurences of old_cdb_path with ‘<cdb_name>’ in string_file.

Parameters:

• string_file (str) – String file
• old_cdb_path (str) – Filepath to a cdb which should be replaced.
• cdb_name (str) – Name of the cdb with which to replace the old file path.

adamspy.adripy.drillsim module

Module for the DrillSim class

class adamspy.adripy.drillsim.DrillSim(string, event, solver_settings, directory, analysis_name, write_TO_files=True)

Bases: object

Contains data defining the files that make up an Adams Drill input deck.

Parameters:

• string (DrillString) – DrillString object representing the string to be used in the simulation
• event (DrillEvent) – DrillEvent object representing the string to be used in the simulation
• solver_settings (DrillSolverSettings) – DrillSolverSettings object representing the string to be used in the simulation
• directory (str) – Path to the directory in which to put the simulation files
• analysis_name (str) – Name of the analysis. Used for all file prefixes

string

DrillString object representing the string to be used in the simulation

Type:DrillString

event

DrillEvent object representing the string to be used in the simulation

Type:DrillEvent

solver_settings

DrillSolverSettings object representing the string to be used in the simulation

Type:DrillSolverSettings

directory

Path to the directory in which to put the simulation files

Type:str

analysis_name

Name of the analysis. Used for all file prefixes

Type:str

string_filename

Filename of the analysis’ string file relative to directory

Type:str

adm_filename

Filename of the analysis’ adm file relative to directory

Type:str

acf_filename

Filename of the analysis’ acf file relative to directory

Type:str

cmd_filename

Filename of the analysis’ cmd file relative to directory

Type:str

res_filename

Filename of the analysis’ res file relative to directory

Type:str

results

Simulation results

Type:dict

results_units

Units of simulation results

Type:dict

pason_inputs

Contains the cleaned pason signals that will be used as inputs to the Adams model. Keys are ‘time’, ‘rop’, ‘wob’, ‘rpm’, and ‘gpm’. Each value is a list with two entries. The first is the signal and the second is the associated time.

Type:dict

built

Indicates whether the input deck (adm, acf, and cmd files) has been built yet for this DrillSim

Type:bool

solved

Indicates whether the DrillSim has been solved and results file (.res) has been generated.

Type:bool

RAMP_TIME

Class attribute containing standard ramp times for rpm, gpm, wob, and rop

Type:dict

CUTOFF_FREQ

Class attribute containing default cutoff frequencies for smoothing pason inputs.

Type:dict

Example

>>> my_drillsim = adripy.DrillSim(my_string, my_event, my_solversettings, os.getcwd(), 'MyAnalysis')

CUTOFF_FREQ = {'rop': 0.1, 'wob': 0.1}

RAMP_TIME = {'gpm': 20, 'rpm': 10}

build(wait=True)

This method builds the input deck. It launches Adams View in batch, reads in the self.string.filename and self.solver_settings.filename files, and runs the Adams Drill macro ds tostart to build a drill string model. Then it saves the model files (.acf, .adm, and .cmd) to the self.directory directory.

Parameters:wait (bool) – If True, code execution waits until the build process terminates before moving on. (default is True)

classmethod clean_pason(pason_data, sig_type, t_min=None, t_max=None, show_plot=True, ramp_time=None, cutoff_freq=None)

Returns a cleaned up pason signal to be used as input to an Adams Drill model.

Parameters:

• pason_data (PasonData) – Pason signal to be used as input.
• sig_type (str) – Type of signal. Options are ‘wob’, ‘rpm’, ‘gpm’, or ‘rop’.
• t_min (float) – Minimum time to crop to the dataset to. (default is None which uses the beginning of the dataset)
• t_max (float) – Maximum time to crop the dataset to. (default is None which uses the end of the dataset)
• show_plot (bool, optional) – If True, shows a plot of the resulting setpoints (the default is True)

Returns:

• list – Cleaned signal
• list – Associated time signal

get_duration(use_acf=False)

Returns the duration of the DrillSim simulation based on contents of the acf file or the msg file.

Parameters:use_acf (bool (optional)) – Set this to True if you want to use the acf file even if the DrillSim has been solved. (the default is False) Returns:Duration of the simulation Return type:float

classmethod get_filtered_signal(pason_data, sig_type, cutoff_freq=None)

Gets a filtered signal from the wob or rop data of a PasonData object.

This method uses a digital zero-phase 5th order butterworth filter with a

Parameters:

• pason_data (PasonData) – A PasonData object
• sig_type (str) – Type of signal. Options are ‘wob’ or ‘rop’
• cutoff_freq (float, optional) – Cutoff frequency to be used in the lowpass filter. (the default is None, which uses value from PasonData.CUTOFF_FREQ)

Raises:

ValueError – Raised if sig_type isn’t ‘wob’ or ‘rop’

Returns:

• list – Filtered signal
• list – Time associated with filterd signal

get_pason_inputs(pason_data, t_min=None, t_max=None, sig_types=['wob', 'rpm', 'gpm', 'rop'], show_plots=True)

Extracts the wob, rpm, gpm, and/or rop from a PasonData object. If this is run before build() the pason data will be added to the adm file as model input splines.

Parameters:

• pason_data (PasonData) – A PasonData object from which input splines will be extracted.
• t_min (float, optional) – Minimum time to extract. (the default is None, which starts at the beginning of the dataset)
• t_max (float, optional) – Maximum time to extract (the default is None, which goes to the end of the dataset)
• sig_types (list, optional) – Signal types to extract. Options are ‘wob’, ‘rpm’, ‘gpm’, ‘rop’. (the default is [‘wob’, ‘rpm’, ‘gpm’, ‘rop’])

classmethod get_stepped_signal(pason_data, ramp_time, sig_type, show_plot=True)

Gets the stepped signal from the rpm or gpm setpoints of a PasonData object.

Parameters:

• pason_data (PasonData) – A PasonData object.
• ramp_time (float) – Time it takes to ramp the signal
• sig_type (str) – Type of signal options are ‘rpm’ or ‘gpm’
• show_plot (bool) – If True, shows a plot of the resulting setpoints (the default is True)

Returns:

• list – Stepped signal
• list – Associated time signal

launch_ppt(wait=False)

Launches the postprocessor and loads res_filename

Parameters:wait (bool, optional) – If True, code execution will freeze until the postprocessor is closed. (the default is False) Raises:FileNotFoundError – Raised if no results file exists in directory.

modify_solver_settings(new_solver_settings)

Modifies the contents of the Adams Command (.acf) file given in acf_file to apply the solver settings specified in the Solver Settings (.ssf) file given in ssf_file.

Parameters:solver_settings (DrillSolverSettings) – Solver settings to use in updating the Adams Command file.

Note

If the DrillSim.built is True, Only the static equilibrium funnel and the integrator error are modified

classmethod read_from_directory(directory)

Returns a DrillSim object from an existing directory that was previously created by a DrillSim object.

Note

This method does not read the pason_inputs attribute

Parameters:directory (str) – Path to a directory previously created by a DrillSim object. Returns:DrillSim object created from an existing directory that was previously created by a DrillSim object. Return type:DrillSim

read_results(reqs_to_read=None, t_min=None, t_max=None, shrink_results_file=False, overwrite_pickle=False, use_iterparse=False)

Reads results from the results file.

Example

>>> drillsim.run()
>>> t_min = 70
>>> t_max = 71
>>> reqs_to_read = {}
>>> reqs_to_read['MSE'] = ['Instantaneous_Bottom_MSE', 'Filtered_Surface_MSE']
>>> reqs_to_read['ROP_controls'] = ['Command_ROP', 'True_WOB']
>>> results, units = drillsim.read_results(reqs_to_read, t_min, t_max)
>>> results['MSE']['Instantaneous_Bottom_MSE']
[5000.5621, 5000.8913, ]

Parameters:

• reqs_to_read (dict, optional) – Dictionary of results data (the default is None, which gets all the results)
• t_min (float, optional) – Mininmum time for which to get results (the default is None, which gets results starting at the first time step)
• t_max (float, optional) – Maximum time for which to get results (the default is None, which gets results up to the last time step)
• shrink_results_file (bool, optional) – If True, the results file will be rewritten to include only the requests in reqs_to_read and the time period between t_max and t_min.

run(wait=True)

Run the simulation

Parameters:wait (bool) – If True the application will wait for the process to complete before continuing.

write_tiem_orbit_files()

Writes the solver settings and event files and publishes the string file to the simulation directory.

Note

When the string file gets published, all the supporting tool files and the hole file are copied to the simulation directory.

adamspy.adripy.event module

Contains the DrillEvent class

class adamspy.adripy.event.DrillEvent(event_name, start_depth, off_bottom, **kwargs)

Bases: object

Creates an object with all data necessary to write a drill event. Once the DrillEvent is instanced ramp parameters must be defined before the DrillEvent is written to an event file.

Note

After instancing the class, at least one simulation step must be added using the add_simulation_step() method. Also, at least one ramp must be added for each of the four drilling parameters (i.e. wob, rpm, gpm, rop) using the add_ramp() method. All other parameters in the event file can be specified when the DrillEvent is instanced using kwargs or they can be set later using:

>>> drill_event.parameters[parameter] = value

Note

WOB should be in lbf

parameters

Dictionary of parameters that make up an Adams Drill string and would be found in an Adams Drill String file (.str). The keys of the dictionary are the parameter names that would be seen in the string file and the values of the dictionary are the values that would be seen in the string file.

Type:dict

filename

Name of the event file (.evt) in which this event is stored. This attribute is initially empty and is populated by the write_to_file() method.

Type:str

add_ramp(parameter, start_time, ramp_duration, delta, clear_existing=False)

Adds a ramp to the specified ramp parameter.

Parameters:

• parameter (str) – ramp parameter, options are ‘TOP_DRIVE’, ‘WOB’, ‘FLOW_RATE’, or ‘ROP’
• start_time (float) – Start time of the ramp.
• ramp_duration (float) – Duration of the ramp.
• delta (float) – Delta of the ramp. Units should be in rpm, lbf, gpm, or ft/sec.
• clear_existing (bool) – If true, existing ramps for the specified parameter will be deleted.

add_simulation_step(end_time, output_step_size=0.05, clear_existing=False)

Adds a dynamic simulation step.

Parameters:

• end_time (float) – End time of the step in seconds.
• output_step_size (float) – Output step size of the step in seconds. (defaults is 0.05)

classmethod read_from_file(filename)

Reads an Adams Drill event (.evt) file and sets DrillEvent.parameters based on data in the file.

Parameters:filename (str) – Filename of an Adams Drill event (.evt) file.

validate()

Determines if all parameters have been set

Returns:True if all parameters have been set. Otherwise False. Return type:bool

write_to_file(directory=None, filename=None, cdb=None)

Creates an event file from the DrillEvent object.

Note

Uses file version 1.0

Parameters:

• write_directory (str) – Directory in which to write the file. Defaults to current working directory.
• filename (str) – Name of the file to write. Defaults to self.parameters[‘EVENT_NAME’]
• cdb (str) – Name of the cdb in which to write the file. This argument overrides the write_directory.

Raises:

ValueError – Raised if not all parameters have been defined.

adamspy.adripy.hole module

Module for working with Adams Drill Hole (.hol) files

class adamspy.adripy.hole.DrillHole(hole_name, **kwargs)

Bases: object

An object with all the data necessary to write an Adams Drill hole (.hol) file.

Parameters:hole_name (str) – Name of the hole object

parameters

Dictionary of parameters that make up an Adams Drill hole and would be found in an Adams Drill hole (.str) file. The keys of the dictionary are the parameter names that would be seen in the hole file and the values of the dictionary are the values that would be seen in the hole file.

Type:dict

filename

Name of the file that the hole object was read from or last written to.

Type:str

get_tvd(md)

Returns the true vertical depth (TVD) corresponding to the provided measured depth (MD).

Parameters:md (float) – Measured depth for which true vertical depth should be returned Returns:True vertical depth corresponding to the given measured depth Return type:float

modify_table(param_name, md_start, md_end, new_values)

Modifies the table parameter with key param_name in the range defined by md_start and md_end.

Note

Use this method to modify the following items in DrillHole.parameters: * Centerline * Diameter * Wall_Contact * Wall_Friction DO NOT MODIFY OR SET THESE ITEMS DIRECTLY. They will not write correctly when the DrillHole.write_to_file() is called.

Note

This method does not work on hole tables that use constant property notation (i.e. single row with measured depth equal to -1)

Examples

Modifying the wall contact parameters between 3000 and 4000 feet. >>> drill_hole.parameters[‘Wall_Contact’] [[0, 1000, 2000, 3000, 4000], [1.0e5, 1.0e5, 1.0e5, 1.0e6, 1.0e6], [1.0e3, 1.0e3, 1.0e3, 2.0e3, 2.0e3]] >>> md_start = 3000 >>> md_end = 4000 >>> k = 1.0e7 >>> c = 3.0e3 >>> contact = [k, c] >>> drill_hole.modify_table(‘Wall_Contact’, md_start, md_end, contact) >>> drill_hole.parameters[‘Wall_Contact’] [[0, 1000, 2000, 3000, 4000], [1.0e5, 1.0e5, 1.0e5, 1.0e7, 1.0e7], [1.0e3, 1.0e3, 1.0e3, 3.0e3, 3.0e3]]

Modifying the dynamic friction coefficient between 3000 and 4000 feet, but leaving the other friction parameters alone. >>> drill_hole.parameters[‘Wall_Friction’] [[0, 1000, 2000, 3000, 4000], [0.9, 0.9, 0.9, 0.9, 0.9], [0.15, 0.15, 0.15, 0.15, 0.15], [0.3, 0.3, 0.3, 0.3, 0.3], [0.3, 0.3, 0.3, 0.3, 0.3]] >>> md_start = 3000 >>> md_end = 4000 >>> mu_d = 0.6 >>> friction = [None, None, mu_d, None] >>> drill_hole.modify_table(‘Wall_Friction’, md_start, md_end, friction) [[0, 1000, 2000, 3000, 4000], [0.9, 0.9, 0.9, 0.9, 0.9], [0.15, 0.15, 0.15, 0.15, 0.15], [0.6, 0.6, 0.6, 0.6, 0.6], [0.3, 0.3, 0.3, 0.3, 0.3]]

Parameters:

• param_name (str) – Name of the parameter to be modified. Must match a key in DrillHole._TABLE_PARAMETERS
• md_start (float) – Start of measured depth range to be modified.
• md_end (float) – End of measured depth range to be modified.
• new_values (list of :obj:`float`s) – New parameter values. The order of this list must match the order in which these parameters are listed in the table in the Adams Drill Hole (.hol) file.

classmethod read_from_file(filename)

Reads an Adams Drill hole (.hol) file and sets DrillHole.parameters based on data in the file.

Parameters:filename (str) – Filename of an Adams Drill hole (.hol) file.

set_table(param_name, values)

Sets the table parameter with the key param_name.

Note

Use this method to set the following items in DrillHole.parameters: * Centerline * Diameter * Wall_Contact * Wall_Friction DO NOT MODIFY OR SET THESE ITEMS DIRECTLY. They will not write correctly when the DrillHole.write_to_file() is called.

Example

>>> md = [0, 1000, 2000, 3000, 4000]
>>> mu_s = [0.7, 0.7, 0.7, 0.8, 0.8]
>>> v_s = [0.1, 0.1, 0.1, 0.1, 0.1]
>>> mu_d = [0.5, 0.5, 0.5, 0.6, 0.6]
>>> v_d = [0.2, 0.2, 0.2, 0.2, 0.2]
>>> friction = [md, mu_s, v_s, mu_d, v_d]
>>> drill_hole.set_table('Wall_Friction', friction)
>>> drill_hole.parameters['Wall_Friction']
[[0, 1000, 2000, 3000, 4000], [0.7, 0.7, 0.7, 0.8, 0.8], [0.1, 0.1, 0.1, 0.1, 0.1], [0.5, 0.5, 0.5, 0.6, 0.6], [0.2, 0.2, 0.2, 0.2, 0.2]]

Parameters:

• param_name (str) – Name of the parameter to be modified. Must match a key in DrillHole._TABLE_PARAMETERS
• values (list of :obj:`list`s) – Parameter values. The order of this list must match the order in which these parameters are listed in the table in the Adams Drill Hole (.hol) file.

validate()

Determines if all parameters have been set

Returns:True if all parameters have been set. Otherwise False. Return type:bool

write_to_file(directory=None, filename=None, cdb=None)

Writes an Adams Drill hole (.hol) file from the object.

Parameters:

• write_directory (str) – Directory in which to write the file. Defaults to current working directory.
• filename (str) – Name of the file to write. Defaults to self.parameters[‘Hole_Name’]
• cdb (str) – Name of the cdb in which to write the file. This argument overrides the write_directory.

Raises:

ValueError – Raised if not all parameters have been defined.

adamspy.adripy.solver_settings module

Contains the DrillSolverSettings class

class adamspy.adripy.solver_settings.DrillSolverSettings(name, **kwargs)

Bases: object

Creates an object with all data necessary to write an Adams Drill solver settings (.ssf) file.

Note

The static funnel is stored as a list of list`s in the 'Funnel' entry of the :attr:`parameters attribute.

Examples

This example reads a DrillSolverSettings object from a file and prints Maxit from all the steps in the static funnel.

>>> ssf = DrillSolverSettings.read_from_file('example.ssf')
>>> maxit = ssf.parameters['Funnel'][0]
>>> print(maxit)
[500, 500, 51, 52, 53, 54, 55, 56, 57, 58, 59, 60, 61, 62, 63, 100]

name

Name of the solver settings object

Type:str

parameters

Dictionary of parameters that make up an Adams Drill solver settings and would be found in an Adams Drill solver settings file (.ssf). The keys of the dictionary are the parameter names that would be seen in the string file and the values of the dictionary are the values that would be seen in the string file.

Type:dict

filename

Name of the solver settings file (.ssf) in which these solver settings are stored. This attribute is initially empty and is populated by the write_to_file() method.

Type:str

add_funnel_step(maxit, stab, error, imbal, tlim, alim, clear_existing=False)

Adds a ramp to the specified ramp parameter.

Parameters:

• maxit (int) – Specifies the maximum number of iterations allowed for finding static equilibrium
• stab (float) – Specifies the fraction of the mass and damping matrices (subsets of the equilibrium Jacobian matrix) Adams Solver (C++) adds to the stiffness matrix (a subset of the equilibrium Jacobian matrix) during static simulations performed using static analyses.
• error (float) – Specifies the relative correction convergence threshold.
• imbal (float) – Specifies the equation imbalance convergence threshold.
• tlim (float) – Specifies the maximum translational increment allowed per iteration.
• alim (float) – Specifies the maximum angular increment allowed per iteration during a static or quasi-static equilibrium analysis.

classmethod read_from_file(filename)

Reads a string file and returns a DrillString object with DrillString.parameters based on data in the string file.

Parameters:filename (str) – Filename of a drill string (.str) file. Returns:DrillSolverSettings object with parameters from the passed solver settings file. Return type:DrillSolverSettings

validate()

Determines if all parameters have been set

Returns:True if all parameters have been set. Otherwise False. Return type:bool

write_to_file(filename, directory=None, cdb=None)

Creates a solver settings file from the DrillSolverSettings object.

Parameters:

• filename (str) – Name of the file to write.
• directory (str) – Directory in which to write the file. (default is None which means it is written to the current working directory.
• cdb (str) – Name of the cdb in which to write the file. This argument overrides directory.

Raises:

ValueError – Raised if not all parameters have been defined.

adamspy.adripy.string module

A module that contains the DrillString class

class adamspy.adripy.string.DrillString(string_name, hole_file, event_file, **kwargs)

Bases: object

An object with all data necessary to write a drill string.

Parameters in the string file can be specified when the DrillString is instanced using kwargs or they can be set later using:

>>> drill_string.parameters[parameter] = value

Note

Once the DrillString is instanced, tools within the string must be defined as DrillTool objects before the string is written to a string file. Use the add_tool() method to add DrillTool objects to the string.

parameters

Dictionary of parameters that make up an Adams Drill string and would be found in an Adams Drill string file (.str). The keys of the dictionary are the parameter names that would be seen in the string file and the values of the dictionary are the values that would be seen in the string file.

Type:dict

tools

List of tools in the drill string. Each element of the list is a dictionary with the keys ‘DrillTool’, ‘Name’, ‘Property_File’, ‘Measure’, ‘Color’, ‘Number_of_Joints’, and ‘Stack_Order’.

Type:list

top_drive

Describes the top drive. The keys are ‘DrillTool’, ‘Type’, ‘Name’, and ‘Property_File’.

Type:dict

add_measurement_point(distance)

Adds a measurement point at the given distance from the bit in feet.

Parameters:distance (float) – Distance from the bit (in feet) at which to place a measurement point.

add_tool(drill_tool, joints=1, measure=False, stack_order=None, color='Default', group_name=None, equivalent=False)

Adds a DrillTool object to the DrillString.

Note

You cannot add the same DrillTool object to the string multiple times. If you want to add multiple instances of the same tool you must create two seperate DrillTool objects from the same Tiem Orbit property file.

Parameters:

• drill_tool (DrillTool) – DrillTool object representing the tool to be added
• joints (int) – Number of Joints. Note that this only applies for certain tool types. (default is 1)
• measure (bool) – If TRUE indicates that output requests should be generated for this tool. (default is FALSE)
• stack_order (int) – If an integer is given the tool will be inserted into the string at that point. (default is None which means the tool will be appended to the end)
• color (str) – The color used to render the tool in an Adams Drill animation. (default is ‘Default’)
• group_name (str) – This argument is required if the tool being added is a tool that comes in multiple joints (e.g. drill_pipe). NOTE: Tools that come in multiple joints are listed in DrillTool._MULTI_JOINT_TOOLS.
• eqivalent (bool) – Set this to True if the tool being added is drill_pipe and you want to use the equivalent upper string formulation.

check_for_references(filename)

Checks for references to filename in the string. Returns the number of references found.

Parameters:filename (str) – Filename to find references to. Returns:Number of references found. Return type:int

get_bha_length()

Gets the total length of the BHA defined in string_file

Note

The BHA is all the tools EXCEPT the equivalent upper string and highest most physical string.

Returns:float Return type:Cumulative length of the bha

get_tool(tool_type, index=0)

Returns a DrillTool object of type tool_type in the DrillString object’s tools list.

Parameters:

• tool_type (str) – Desired tool type.
• index (int) – Index of the tool to return (the default is 0)

Raises:

DrillStringError – Raised if a tool of the specified type does not exist in the drill string.

Returns:

DrillTool object

Return type:

DrillTool

classmethod read_from_file(filename)

Reads a string file and returns a DrillString object with DrillString.parameters based on data in the string file.

Parameters:filename (str) – Filename of a string file. Returns:DrillString object with parameters from the passed string file. Return type:DrillString

set_pipe_joints(joints, equivalent=False)

Sets the number of joints in the upper most section of drill pipe. Set equivalent=True to adjust equivalent upper string joints.

Parameters:

• joints (int) – Number of physical drill pipe joints.
• equivalent (str) – False for physical string. True for equivalent upper string. (Default is False.)

Raises:

DrillStringError – Raised if the drill string doesn’t have drill pipe of the specified type.

tool_renamed(renamed_tool)

Updates the ‘name’ and ‘Property_File’ entries in the tools to match renamed_tool.name.

Parameters:renamed_tool (DrillTool) – DrillTool object that has been renamed and needs to have its ‘Name’ and ‘Property_File’ entries updates.

validate()

Determines if all parameters have been set.

Returns:dict with a valid key with a boolean value indicating whether the string was successfully validated and a reason key with a str value indicating the reason (if any) that the string was not successfully validated. Return type:dict

write_to_file(directory=None, filename=None, cdb=None, publish=False, publish_event=False)

Writes a string file from the DrillString object.

Notes

There are no required parameters. However, either directory or cdb must be defined. Otherwise write_to_file() raises a ValueError.

When publishing to a directory, relative paths will be used for all filenames in the string file.

Parameters:

• directory (str) – Directory in which to write the file. (default is None which means the string will be written to the cdb given in cdb.)
• cdb (str) – Name of the cdb in which to write the file. This argument is overridden by directory. (default is None which means the string will be written to the directory in directory and will use the filename in filename.)
• publish (bool) – If True, writes all the supporting files except the event file to the same cdb or directory. (default is False.)
• publish_event (bool) – If True, writes the event file to the same cdb or directory. (default is False.)

Raises:

• ValueError – Raised if neither directory nor cdb are given.
• RuntimeError – Raised if not all parameters have been defined.

exception adamspy.adripy.string.DrillStringError

Bases: Exception

adamspy.adripy.tool module

Contains the DrillTool class

class adamspy.adripy.tool.DrillTool(property_file)

Bases: object

Object representing an Adams Drill tool. Instances must be generated from a tool property file.

property_file

Tiem Orbit file representing the drill tool.

Type:str

name

Name of the tool.

Type:str

tool_type

Type of the tool.

Type:str

extension

Extension used for tiem orbit file

Type:str

table

Name of the cdb table used for the particular tool type

Type:str

bind_name_to(name_receiver)

Appends name_receiver to _name_receivers.

All the methods in the name_receiver :obj:list will be called anytime the rename() method is called

Parameters:name_receiver (func) – Any method that takes a DrillTool.

copy_file(directory=None, cdb=None)

Copies the file to directory or to the appropriate table in cdb.

Parameters:

• write_directory (str) – Directory in which to write the file. (default is None.)
• cdb (str) – Name of the cdb in which to write the file. This argument overrides the directory. (default is None.)

Raises:

• ValueError – Raised if neither directory nor cdb are given.
• ValueError – Raised if not all parameters have been defined.

Note

Either directory or cdb must be given.

get_parameter_value(parameter_to_get)

Returns the value of the specified parameter from the property file.

Note

This method cannot get parameters from the UNITS block.

Parameters:parameter_to_get (str) – Name of the parameter to get from the property file. Returns:Value of the specified parameter from the property file. Return type:string or float

modify_parameter_value(parameter_to_change, new_value)

Modifies a parameter in a DrillTool property file.

Parameters:

• parameter_to_change (str) – Name of the parameter to modify. Must match the name in the property file. (Not case sensitive).
• new_value (float or str) – New value of the parameter to change
• new_filename (str) – Filename of new property file. If None the original property file will be overwritten (the default is None.)

rename(new_name, remove_original=False)

Renames the tool

Note

If this tool is part of a DrillString object, the DrillString object will be updated with the new name and property file.

Parameters:

• new_name (str) – New name for the tool.
• remove_original (bool) – If True will rename the property file. If False will create a new one.

exception adamspy.adripy.tool.DrillToolError

Bases: Exception

adamspy.adripy.utilities module

adripy contains functions for manipulating MSC Adams Drill files

class adamspy.adripy.utilities.MotorModel(min_rpms, max_rpms, flows, stall_torque, max_torque)

Bases: object

classmethod build_from_coeffs(nor_max_rpm_a, nor_max_rpm_b, nor_min_rpm_a, nor_min_rpm_b, max_torque, stall_torque)

Used to build a motor model if you already know the motor coefficients.

Parameters:

• nor_max_rpm_a (float) – nor_max_rpm_a
• nor_max_rpm_b (float) – nor_max_rpm_b
• nor_min_rpm_a (float) – nor_min_rpm_a
• nor_min_rpm_b (float) – nor_min_rpm_b
• max_torque (float) – max_torque
• stall_torque (float) – stall_torque

Returns:

A MotorModel object

Return type:

MotorModel

degrade_motor(degradation)

Degrades the motor by degradation (in place)

Parameters:degradation (float) – Motor degradation factor

get_motor_curve(flow)

Returns data t`o generate a theoretical motor curve.

Parameters:flow (float) – Flow rate at which to generate the motor curve Returns:

• list – Rpm points in normal operating range
• list – Rpm points in extended stall range range
• list – Torque points in normal operating range
• list – Torque points in extended stall range range

Example

This example plots the motor curve with a dashed line for the extended stall range. >>> import matplotlib.pyplot as plt >>> stall_torque = 20 >>> max_torque = 15 >>> max_rpms = [80, 100, 120] >>> min_rpm = [50, 70, 90] >>> flows = [400, 500, 600] >>> motor_model = MotorModel(min_rpms, max_rpms, flows, stall_torque, max_torque) >>> nor_rpm, esr_rpm, nor_torque, esr_torque = motor_model.get_motor_curve(550) >>> plt.plot([rpm + min_rpm for rpm in nor_rpm], nor_torque) >>> plt.plot(esr_rpm, esr_torque, linestyle=’–’) >>> plt.show()

get_torque(rpm, flow, degradation=1)

Gets the motor output torque given a motor rpm and flow rate.

Parameters:

• rpm (float) – Motor rpm
• flow (float) – Motor flow rate
• degradation (float) – Motor degradation factor (default is 1 which means there is no degradation)

Returns:

Motor output torque

Return type:

float

Raises:

MotorModelError – Raised if the rpm given is greater than the motors maximum output rpm.

exception adamspy.adripy.utilities.MotorModelError

Bases: Exception

exception adamspy.adripy.utilities.TiemOrbitSyntaxError

Bases: Exception

adamspy.adripy.utilities.add_cdb_to_cfg(name, loc, cfg_file)

Adds cdb of name name and path loc to cfg_file

Parameters:

• name (str) – Name of cdb (e.g. example_database)
• loc (str) – path to cdb (e.g. C:example_database.cdb)
• cfg_file (str) – Full filename of an adams drill configuration file

Raises:

• ValueError – Raised if a cdb of the given name or path already exists in the given config file
• PermissionError – Raised if the user does not have permissiosn to edit the given config file

adamspy.adripy.utilities.add_splines_to_acf(acf_file)

Adds spline references to the input variable function statements in an Adams Drill Command (.acf) file.

Parameters:acf_file (str) – File name of an Adams Drill Command (.acf) file.

adamspy.adripy.utilities.add_splines_to_adm(adm_file, splines)

Adds splines inputs to an Adams Drill dataset (.adm) file.

Adds a block titled SPLINES above the OUTPUT block of the ADM file. The SPLINES block contains a SPLINE statement for each of the four drilling parameters.

Example

>>> time = [0.0, 1.0, 2.0, 3.0, 4.0, 5.0, 6.0, 7.0, 8.0, 9.0, 10.0]
>>> gpm = [0, 78.125, 250.0, 421.875, 500, 500, 500, 500, 500, 500, 500]
>>> rpm = [0, 0, 0, 0, 12, 37, 50, 50, 50, 50, 50]
>>> wob = [0, 0, 0, 0, 0, 0, 0, 10, 29, 40, 40]
>>> rop = [0, 0, 0, 0, 0, 0, 0, 25, 74, 100, 100]
>>> splines = {}
>>> splines['gpm'] = [time, gpm]
>>> splines['rpm'] = [time, rpm]
>>> splines['wob'] = [time, wob]
>>> splines['rop'] = [time, rop]
>>> adm_file = 'demo.adm'
>>> add_splines_to_adm(adm_file, splines)

Parameters:

• adm_file (str) – Filename of Adams Drill dataset (.adm) file
• splines (dict) – Dictionary containing the spline data for the four drilling parameters. See Example for dictionary makeup.

adamspy.adripy.utilities.build(string_file, solver_settings_file, working_directory, output_name=None, wait=True)

Builds adm, acf, and cmd files from string, event, and solver settings files.

Parameters:

• string (str) – Filename of a drill string (.str) file.
• solver_settings (str) – Filename of a solver settings (.ssf) file.
• working_directory (str) – Path to the directory to put the adm, acf, and cmd
• output_name (str) – Base name of the adm, acf, and cmd files. (the default is none, which redefines the ouput_name to be the same as the ‘OutputName’ parameter in the string file)
• wait (bool) – If True, code execution waits until the build process terminates before moving on. (default is True)

Returns:

• str – Filename of the adams dataset (.adm) file.
• str – Filename of the adams command (.acf) file.
• str – Filename of the adams view command (.cmd) file.

exception adamspy.adripy.utilities.cdbError

Bases: Exception

adamspy.adripy.utilities.cdbNotation_to_fullNotation(string_file)

Replaces all references in a string file that use CDB notation to use full path notation

Parameters:string_file (str) – Full path to an Adams Drill string file Returns:Number of replacements made Return type:int

adamspy.adripy.utilities.create_cfg_file(filename, database_paths)

Create a cfg file with the databases whose paths are given in the database_paths list. Also sets the ADRILL_USER_CONFIG environment variable equal to filename.

Parameters:

• filename (str) – Filename for the new configuration file.
• database_paths (list) – List of database paths to include in the configuration file.

adamspy.adripy.utilities.fullNotation_to_cdbNotation(string_file)

Replaces all references in a string file that use full path notation to use CDB notation

Parameters:string_file (str) – Full path to an Adams Drill string file Returns:Number of replacements made Return type:int

adamspy.adripy.utilities.get_TO_param(filename, requested_parameter)

Return the value of a parameter in a tiem orbit file

Parameters:

• filename (str) – Path to a tiem orbit file. Accepts full path or cdb alias.
• requested_parameter (str) – Name of a parameter in TO_file

Returns:

The value assigned to TO_param in TO_file

Return type:

str or int or float

adamspy.adripy.utilities.get_adrill_cdbs(adrill_user_cfg, adrill_shared_cfg=None)

Return the names and locatinos of all user defined MSC Adams Drill databases (cdbs)

Parameters:

• adrill_user_cfg (str) – Full path to an Adams Drill user configuration file. This hould be in the users HOME directory.
• adrill_shared_cfg (str) – Full path to an Adams Drill shared configuration file. This should be in the Adams Drill installation directory. (the default is None, which means that only user cdbs will be returned.)

Returns:

A dictionary in which the cdb names are keys and the cdb locations are values.

Return type:

dict

adamspy.adripy.utilities.get_bha_length(string_file)

Gets the total length of the drill string defined in string_file NOT including the equivalent upper string and highest most physical string

Parameters:string_file (str) – Full path to an Adams Drill string file Returns:Cumulative length of the string Return type:float

adamspy.adripy.utilities.get_cdb_location(cdb_name)

Returns the location of cdb ‘cdb_name’

Parameters:cdb_name (str) – Alias of a cdb Returns:Location of cdb Return type:str

adamspy.adripy.utilities.get_cdb_path(full_filepath)

Given the full path to a file located in a cdb, get_cdb_path returns the path to a file with the cdb path replaced by the cdb alias. full_filepath will be returned if no cdb is found in the path.

Parameters:full_filepath (str) – Full file path to a file in a cdb Returns:Path to a file with the cdb path replaced by the cdb alias. Return type:str

adamspy.adripy.utilities.get_full_path(cdb_filepath)

Given the cdb path to a file located in a cdb, returns the path to a file with the cdb alias replaced by the cdb location. If cdb_filepath does not use cdb notation, returns the full filepath (convertes a relative filepath to a full filepath).

Note

cdb_filepath is not case sensitive.

Parameters:cdb_filepath (str) – Full file path to a file in a cdb. Returns:Path to a file with the cdb path replaced by the cdb alias. Return type:str

adamspy.adripy.utilities.get_motor_coefficients(min_rpms, max_rpms, flows)

Returns the motor coefficients used in the Adams Drill motor model.

Parameters:

• min_rpms (list) – List of the minimum operating motor speeds for each flow rate.
• max_rpms (list) – List of the maximum operating motor speeds for each flow rate.
• flows (list) – List of corresponding flow rates

Returns:

• float – NOR Max (No Load) RPM A
• float – NOR Max (No Load) RPM B
• float – NOR Min (Max dP) RPM A
• float – NOR Min (Max dP) RPM A

adamspy.adripy.utilities.get_motor_curve(stall_torque, max_torque, max_rpm, min_rpm, save_filename=None)

Returns data to generate a theoretical motor curve.

Parameters:

• stall_torque (float) – Torque at which the motor stalls (klbf-ft)
• max_torque (float) – Maximum operating torque (klbf-ft)
• max_rpm (float) – Maximum operating motor speed
• min_rpm (float) – Minimum operating motor speed
• save_filename (bool, optional) – If True, motor curve will be saved to file filename, by default None

Returns:

• list – Rpm points in normal operating range
• list – Rpm points in extended stall range range
• list – Torque points in normal operating range
• list – Torque points in extended stall range range

Example

This example plots the motor curve with a dashed line for the extended stall range. >>> import matplotlib.pyplot as plt >>> stall_torque = 20 >>> max_torque = 15 >>> max_rpm = 100 >>> min_rpm = 80 >>> nor_rpm, esr_rpm, nor_torque, esr_torque = get_motor_curve(stall_torque, max_torque, max_rpm, min_rpm) >>> plt.plot([rpm + min_rpm for rpm in nor_rpm], nor_torque) >>> plt.plot(esr_rpm, esr_torque, linestyle=’–’) >>> plt.show()

adamspy.adripy.utilities.get_number_of_tools(string_file)

Gets the total number of tools in a string. Tools for which quantitiiy can be defined are only counted once. The top drive is not included

Parameters:string_file (str) – Full path to an Adams Drill string file Returns:Number of tools Return type:int

adamspy.adripy.utilities.get_string_length(string_file, bha_only=False)

Gets the total length of the drill string defined in string_file

Parameters:

• string_file (str) – Full path to an Adams Drill string file
• bha_only (bool) – If True, ignores the length of top most physical string and equivalent upper string

Returns:

Cumulative length of the string

Return type:

float

adamspy.adripy.utilities.get_tool_name(string_file, tool_type, n=1, return_full_path=True)

Returns the name, filename, stack order, and group name of the n`th tool of type `tool_type in string_file.

Parameters:

• string_file (str) – Path to an Adams drill string file. Accepts full path or cdb alias.
• tool_type (str) – Tool type as seen in the string file (e.g. pdc_bit, motor, stabilizer)
• n (int) – If the string file has multiple tools of type tool_type , returns the n th tool of that type. (the default is 1)
• return_full_path (bool) – If true, returns the full path to the tool file instead of using the Adams Drill database (cdb). (the default is True)

Raises:

ValueError – Raised if a tool of type tool_type is not found in string_file

Returns:

• str – Name of the requested tool
• str – Full filepath the the requested tool’s property file
• int – Stack order of tool
• str – Tool’s group name if it has one

adamspy.adripy.utilities.has_tool(string_file, tool_type)

Returns true if string_file has at least one tool of type tool_type

Parameters:

• string_file (str) – Full path to an Adams Drill string file
• tool_type (str) – Adams Drill tool type

Returns:

True if string_file contains at least one tool of type tool_type

Return type:

bool

adamspy.adripy.utilities.isabs(filename)

Checks if a filepath is absolute.

Note

This function is derived from os.path.isabs(). The only difference is that it returns True if the filepth uses cdb alias names.

Parameters:filename (str) – Path to a file. Can be relateive, absolute, or use cdb aliases. Returns:True if path is absolute or uses cdb aliases. Return type:bool

adamspy.adripy.utilities.modify_acf_solver_settings(acf_file, statics=None, error=None)

Modifies the contents of the Adams Command (.acf) file given in acf_file to apply the static funnel given in statics and the dynamic steps given in dynamics.

Parameters:

• acf_file (str) – Path to Adams Command (.acf) file to be updated
• statics (list) – List of six lists where each list contains the values of a particular equilibrium setting at each step in the funnel. (Defaults to the value already in the acf file.)
• error (float) – Error tolerance to use for the dynamics solver. (Defaults to the value already in the acf file.)

Example

The following example modifies example.acf to have a three-step static funnel and a dynamic solver error tolerance of 0.0001.

>>> maxit = [500, 500, 500]
>>> stab = [8.0, 1.0, .01]
>>> error = [1.0, 0.1, .01]
>>> imbal = [4.0, 2.0, .01]
>>> tlim = [4.0, 2.0, 1.0]
>>> alim = [4.0, 2.0, 1.0] # Assumes DEGREES
>>> statics = [maxit, stab, error, imbal, tlim, alim]
>>> modify_acf_solver_settings('example.acf', statics=statics, error=.0001)

adamspy.adripy.utilities.read_TO_file(filename)

Reads a Tiem Orbit file into a dictionary of parameters

Example

This example prints the value of the Integrator parameter from the DYNAMICS block of a solver settings file.

>>> ssf = read_TO_file('example.ssf')
>>> integ = ssf['DYNAMICS']['Integrator']
>>> print(integ)
HHT

This example prints Maxit from the FUNNEL subblock of the STATICS block of a solver settings file.

>>> ssf = adripy.read_TO_file('example.ssf')
>>> maxit = ssf['STATICS']['FUNNEL']['maxit']
>>> print(maxit)
[100, 50, 50, 50]

Parameters:filename (str) – Filename of the Tiem Orbit file Returns:Nested dict of the blocks, subblocks, and parameters. Return type:dict Raises:TiemOrbitSyntaxError – Raised if the Tiem Orbit syntax is not recognized

adamspy.adripy.utilities.remove_cdb_from_cfg(name, cfg_file)

Removes cdb of name name from cfg_file

Parameters:

• name (str) – Name of cdb (e.g. example_database)
• cfg_file (str) – Full filename of an adams drill configuration file

Raises:

• ValueError – Raised if a cdb of the given name or path already exists in the given config file
• PermissionError – Raised if the user does not have permissiosn to edit the given config file

adamspy.adripy.utilities.replace_tool(string_file, old_tool_file, new_tool_file, old_tool_name='', new_tool_name='', N=0)

Swaps old_tool_file for new_tool_file in string_file. Also replaces the tools Name field.

Parameters:

• string_file (str) – Path to an Adams Drill string file. Accepts full path or cdb aliases.
• old_tool_file (str) – Path to an Adams Drill tool property file that exists in string_file. Accepts full path or cdb aliases.
• new_tool_file (str) – Path to an Adams Drill tool property file to replace old_tool_file. Accepts full path or cdb aliases.
• N (int) – Number of replacements to make. Default is 0 which will replace all instances.
• old_tool_name (str) – Name of the tool to replace. Default is the filename.
• new_tool_name (str) – Name of the new tool. Default is the filename.

Returns:

Number of replacements that were made

Return type:

int

adamspy.adripy.utilities.turn_measure_on(string_file, tool_types=[], tool_numbers=[], tool_names=[])

Modify a string file to turn measure on for teh designated tools. Tools may be designated by type, number (stack order), or name.

Parameters:

• string_file (str) – Path to an MSC Adams Drill string file. Accepts full path or cdb alias.
• tool_types (list, optional) – List of tool types as seen in the string file (e.g. pdc_bit, motor, stabilizer)
• tool_numbers (list, optional) – List of stack orders corresponding to tools in the string
• tool_names (list, optional) – List of tool names

Returns:

number of tools measured

Return type:

int

Module contents

adripy is a set of python tools for manipulating MSC Adams Drill files and data.