QuickStart#

This is a short introduction to the KAPPA-Automate Python SDK, geared mainly for new users. You’ll need to know a bit of Python. For a refresher, see the Python tutorial.

Customarily, we import as follows:

import kappa_sdk as ka

Basic Objects#

Here is an overview of the main objects in the KAPPA-Automate Python SDK:

kappa_sdk.Connection: A class to instantiate a connection to your KAPPA-Automate instance.
kappa_sdk.Field: Presents a KAPPA-Automate field object that can be queried for contained wells.
kappa_sdk.Well: Presents a KAPPA-Automate well object that can be queried for contained data and every existing object under the well.
kappa_sdk.Data: Presents a KAPPA-Automate data object that is used to read and write the vector values.
kappa_sdk.Vector: Container to store dates, values and elapsed times in the same object.
kappa_sdk.Document: Represents a KW document object in KAPPA-Automate, which allows you to access information from the analyses contained within the document. For handling files, the class kappa_sdk.File is used.

These objects form the core components used to interact with KAPPA-Automate, providing a flexible way to handle and manipulate well data, fieldsand associated information programmatically.

Initializing a Connection#

To begin interacting with KAPPA-Automate, you first need to establish a connection to your instance. This can be done by using the kappa_sdk.Connection and specifying the address of your KAPPA-Automate instance.

import kappa_sdk as ka
ka_address = "https://your-ka-instance.com"
connection = ka.Connection(ka_address, verify_ssl=False)

Note

If you are not using SSL certificates, you need to set the verify_ssl parameter to False

Navigating through field hierarchy#

Once the connection is established, you can get access to the field hierarchy using the kappa_sdk.Connection.get_fields method. This will give you a list of kappa_sdk.Field objects.

all_fields = connection.get_fields()
for field in all_fields:
    print(field.name)

From this list of fields, you will be able to retrieve a specific field.

field_name = "Field"
field = next(x for x in all_fields if x.name == field_name)

Note

The next() function is used to retrieve the first item from an iterator that matches a given condition. If you are not familiar with next(), you can read more about it in the official Python documentation or refer to a tutorial on iterators and generators.

After obtaining the desired field, you can access the wells within that field by using the kappa_sdk.Field.wells attribute. Similarly to how you retrieved a field, you can use the next to retrieve a specific well.

all_wells = field.wells
well_name = "Well"
well = next(x for x in all_wells if x.name == well_name)

A more concise version of this example is shown below:

import kappa_sdk as ka

connection = ka.Connection("https://your-ka-instance.com", verify_ssl=False)
field = next(x for x in connection.get_fields() if x.name == "Field")
well = next(x for x in field.wells if x.name == "Well")

Well Data#

A well may contain various types of data, such as gauges, production data, corrected production and more. If you are unsure where your data is located within the well, you can use the Well.data attribute to retrieve all the data under the well and then filter or access it as needed.

However, if you have more knowledge about the data or wish to locate it within a specific category, you can use other attributes, as shown in the following example:

data_name = "Data"
data = next(x for x in well.data if x.name == data_name)
data_production = next(x for x in well.productions if x.name == data_name)
data_gauge = next(x for x in well.gauges if x.name == data_name)
data_corrected_production = next(x for x in well.corrected_productions if x.name == data_name)
data_function = next(x for x in well.functions if x.name == data_name)

Note

Any time series in KAPPA-Automate is considered as a Data object.

Reading Data#

You can read the values from the data object with the kappa_sdk.Data.read() method. It returns a kappa_sdk.Vector object.

vector = data.read()
dates = vector.dates
values = vector.values
elapsed_times = vector.elapsed_times

At times, we may be dealing with several million data points, so reading and processing them all at once may not be practical or even possible. In such cases, you can use the kappa_sdk.Data.read_by_chunks() method that returns an iterator. This way you can process data in chunks of predefined size without having to store the whole content of data in memory.

It is important to remember that all data read from KAPPA-Automate are given in internal units. If you need to convert the data to a specific unit you can use the unit parameter with a kappa_sdk.UnitEnum value. For example you can convert your pressure data to psia values:

pressure_psia = data.read(unit=ka.UnitEnum.pressure_psia)

Note

You can also pass a start date and an end date to the kappa_sdk.Data.read() method

Note

The start date is EXCLUSIVE and the end date is INCLUSIVE.

Writing Data#

Just like when reading data, the first step in writing data to KAPPA-Automate is to obtain a kappa_sdk.Data object.

If you are modifying or appending to existing data, you can retrieve it by navigating the field hierarchy, as shown above.
If you need to create a new data in the well, you can do so by calling the appropriate methods of the :class:kappa_sdk.Well object.

The following example demonstrates how to write data to a new data object:

new_data = well.create_data("New data", "P")
vector = ka.Vector(dates, values)
new_data.append(vector, unit=ka.UnitEnum.pressure_psia)

As for reading data, you can specify the unit of origin of the data with the unit parameter.

Note

In this example we have created a new pressure data, that is normally given “by points”. You can also use the kappa_sdk.Well.create_step_data() to create data given “by step”.

Note

It is important to remember that you need to pass a valid “data-type” alias when creating new data. This “data-type” must be present in the field at the time when you are creating the data. Please see the Data-Types Reference for a list of built-in data-types.

Documents#

Similarly to how you retrieved a data object, you can retrieve documents from your field or well.

document_name = "file.ks5"
field_document = next(x for x in field.documents if x.name == document_name)
well_document = next(x for x in well.documents if x.name == document_name)

Documents only refer to KW documents. If you need to retrieve another type of file:

file_name = "excel.xlsx"
field_file = next(x for x in field.files if x.name == file_name)
well_file = next(x for x in well.files if x.name == file_name)