Python is a powerful environment for creating scientific processing applications, and is ideally suited to creating stand-alone external programs that work with the Geosoft data processing environment. GX Developer includes a Python package that can be installed with Python 3.x to support stand-alone 32-bit or 64-bit Python 3 applications, which will will work with an installed Geosoft Oasis montaj environment (version 8.2 or later). The GX API provides access to all data read and write functions as well as most of Geosoft's processing functionality, which can be combined with Python-oriented processes to create specialized applications or workflows.

Note that as of this writing (Oasis montaj 8.5) only support running Python scripts as an external application independent of a running Oasis montaj session. This is suitable for creating stand-alone Python-oriented workflows that need to work with Oasis montaj projects or data files. If you want to create a workflow that runs from an open Geosoft project, you can also create a Geosoft GX that runs (shells) a Python script (32-bit or 64-bit) to perform the processing function, which then returns control to the running Oasis montaj. The external program is able to to access almost all the functions in the Geosoft API, including the ability to open, read and write Geosoft files. The functions that are not available usually require the Oasis montaj UI and an open project.

Some uses for GX Developer for Python:

Create a stand-alone application to import an unsupported data format into Geosoft.
Export all or selected data from a Geosoft data file to some other format.
Add support for Geosoft data files to Python-based processing environment.
Access Geosoft's advanced processing functions from a Python program.
Create a specialized data processing algorithm that can be applied to data stored in a Geosoft environment.
Create a processing application that takes advantage of a 64-bit memory model and operating system.

Content

Configuring Python for Geosoft development

Configuring your system to run Python involves first installing Python and all the Python packages that your application requires; then installing the Geosoft package specific to your version of Python.

Note that Python can be configured many ways according to the needs of the Python developer. Here we describe the configurations recommended by Geosoft, though advanced Python developers may choose other configuration options. If you choose an alternate configuration you should understand the details of the Geosoft recommendation so that you can configure your system correctly.

Frequently Asked Questions

Python version 2.7 or 3.4? The Geosoft distribution packages only support Python version 3.4. Python 2.7, which was released in 2010, was the end of development for Python 2.x, and for this reason we have chosen not to support Python 2.7 (or earlier). If you are new to Python, you should start with Python 3. If you have legacy Python 2 code that you want to run with a Geosoft environment you may need to make modifications to the code to work with Python 3. See https://docs.python.org/2/howto/pyporting.html for infomation on what may be required to port Python 2 code to Python 3.

Which Python distribution? There are many distributions of Python, but Geosoft uses and recommends the WinPython distribution (http://winpython.sourceforge.net/) as this includes all the packages that are required to work with Geosoft code together with the most important and widely used packages that make up what is considered complete for a scientific application. Most notable among these is SciPy (including NumPy), which is a requirement for Geosoft. At time of writing, the latest Python distribution supported by WinPython is version 3.4, and Geosoft provides a 32-bit and 64-bit package that will work with that version.

32 or 64-bit Python? Geosoft provides packages for both 32-bit and 64-bit Python 3. However, we strongly recommend that you use the 64-bit version for any applications that target modern computers. The only reason to create 32-bit applications would be if you need to run your application on older computers that only have 32-bit Windows installed. Note that any reasonably large Python application will have challenges dealing with the memory limitations of a 32-bit environment, so if you choose to work with 32-bit Python you should be skilled in writing memory-restricted programs. Memory limitations are much less an issue with 64-bit Python applications, though even on 64-bit systems you may find yourself memory-limited for very large processing tasks. Note that the Geosoft libraries that make up the Geosoft environment support both a 32-bit and 64-bit systems, and include a memory manager that detects and optimizes memory usage for either 32-bit or 64-bit memory environments. Geosoft-oriented applications will generally run faster in a 64-bit environment.

Which IDE? Which Integrated Development Environment (IDE) to use is the personal choice of the developer. Although WinPython includes the Spyder IDE, at Geosoft we use and recommend the PyCharm IDE (http://www.jetbrains.com/pycharm/), which has both a no-cost "Community Edition" intended for education and personal use, and a very reasonably priced "Professional Edition" for professional use. Note also that WinPython (and most complete Python distributions such as Anaconda or Canopy) include IPython. Although not strictly an IDE, IPython does provide an environment for rapid algorithm development, experimentation and documentation and can be very good for researchers.

Which GUI? If you are developing simple data processing applications you may not need a GUI development environment. But if you are developing interactive applications you will need to decide which GUI development environment you wish to use. At Geosoft, we use Qt via the PySide API (https://pypi.python.org/pypi/PySide).

GX application or stand-alone? Although the current Python package only supports the creation of stand-alone applications, you may want to create a workflow that runs directly from the context of an open Geosoft project, in which case you will need to create a Geosoft GX that can be launched from Oasis montaj. In this case, you can create a GX that interacts with the user (determines which channels to process, processing parameters, etc.), prepares the project data and runs the Python script as a separate process. The GX then waits for the process to finish, after which resources are re-opened and presented to your user.

Anaconda Python Distribution

For GX Developer 9.1, we recommend using the Anaconda Python 3.5 64-bit distribution for Windows). (https://www.continuum.io/downloads)

Step	What	Comments
1	Install Anaconda 3.5, 64-bit for Windows	Choose the most recent version of 64-bit installer for Windows from https://www.continuum.io/downloads. Add the Anaconda python folder to your system path so that you can run python.exe from the command line. Verify that Anaconda Python 3.5 is installed: open a command shell run `python.exe -Vexpected response:` Python 3.5.1 :: Anaconda 4.0.0 (64-bit) If you do not get the expected Python version number (3.5.x), something went wrong with the installation. Check that the correct python.exe can be found in the system path. If you are managing multiple versions of Python using the Anaconda "conda" package manager, ensure that the correct environment is activated. You may need to activate "py35" by entering: `activate py35`
2	Download and install GX Developer version 9.1	Choose GX Developer 9.1 from https://my.geosoft.com/downloads/gx-developer-toolkit. If you have not registered as a GX Developer, you will first be registered, after which the download will be available and will have access to the GX Developer on-line forum, which can be used to get help using GX Developer and to collaborate with other GX developers.
3	Install the Geosoft Python modules.	After installing GX Developer you will find a folder named "`C:\Program Files\Geosoft\GX Developer (x64)\python\geosoft-gx`", which contains the Geosoft Python packages. Open a command console and go to this folder. Install the Geosoft Pyhon modules by entering: `python setup.py install`
4	Validate your setup	open a command shell run `python.exe` Enter the following four lines: >>> import geosoft.gxpy.gx as gx >>> gxp = gx.GXpy() >>> gxp.gid your Geosoft should be printed to the console >>> exit() The first line imports geosoft.gxpy.gx symbols from the Geosoft GX package. This confirms that the Geosoft Python modules were correctly installed into Python site packages. The second line creates a gx context and returns the context class. If you are NOT signed-in to Geosoft, you will be asked to authenticate who you are. This line is required for any scripts that run outside of Oasis montaj. Scripts that run directly from menus inside Oasis montaj will inherit the working context of Oasis montaj. One of the class members is 'gid', which is your Geosoft ID. The third line displays your Geosoft ID. The third line executes a gx wrapper function, which confirms that the gx context has been correctly initialized and that you have correctly signed in with Geosoft Connect. This function will return 0 if the file exists, or 1 if the file does not exist. The last line exits the Python script. If this test works without reporting errors your system is properly configured.

Python Installed Files

The GX Developer installation contains the following Python specific files:

python\geosoft.gx-py34-8.4.0.win32.exe	Installer for 32-Bit Python distributions. This will install the geosoft site package to registered 32-bit Python 3.4 installation.
python\geosoft.gx-py34-8.4.0.win-amd64.exe	Installer for 64-Bit Python distributions. This will install the geosoft site package to registered 64-bit Python 3.4 installation
python\Python3.4-32\site-packages\geosoft python\Python3.4-64\site-packages\geosoft	Complete site-package folders that can be copied to site-packages folder of a Python installations that does not support "exe" style installations.
python\examples\	This folder contains simple example Python scripts that demonstrate use of the API. See also python.zip v1.1, which includes a GX (python.gx) that will run a python script from Oasis montaj. This includes versions of the example programs that will work with python.gx.

Getting Started with Python

Learning Python

GX Developer for Python is intended for experienced python developers, so learning Python is outside the scope of this document. For new Python developers, there are many online Python resources. You will find that Google search is your best assistant as you learn and continue to use Python. Here are some resources you may find helpful to get you going:

Python.org – the Python.org website has the definitive documentation for every version of Python and has an excellent Python for Beginners section
Google Python Class – Google is a big supporter of Python and has created a pretty good online course.
There is a very nice online Python text at linuxtopia.
Stackoverflow forums are an excellent source of topical help and you will find that Google searchs with questions like "python how do I ...?" will bring you to useful and specific Stackoverflow developer threads.
Experimentation – Python is interactive. You can test and run code as you write it, create functions on the fly and so on. The chanadd2 and chanadd3 code examples in particular are intended to be loaded into a shell and deconstructed.
Code examples – Once you’ve learned a few Python basics, check out the code examples included with this distribution. They include examples of working with databases and grids and demonstrate a number of Python concepts.

API Documentation

You will find the Geosoft Python GX API reference here:

GX Developer 8.5 API reference for Python

Python Samples

Update 2016-2-5

Python.gx is a GX that will run a Python script directly from an open Oasis montaj project. The GX saves all current state information to a YAML file, which the Python script can open to obtain state information, such as the current database, displayed channels, current map, etc. You will find the Python GX and source code, together with script examples here: python.zip v1.1

You will find a number of Python examples in:

C:\Program Files (x86)\Geosoft\GX Developer\apps\examples\python

ChanAdd.py - This is a simple example of reading and writing from a Geosoft database. It also demonstrates working with command line arguments, writing to a file and how to get lists of channels and lines from a database.

GridCopy.py - A simple example showing how to copy a grid. It demonstrates the use of the GXIMG interface

GridFilter.py - This is a more sophisticated grid handling routine. The GXIMU.grid_filt function upon which it depends is complicated, because it is very flexible. It requires 10 parameters, several of which are inter-dependent. The user can specify a predefined filter or a filename containing the filter elements. In the GX version of this utility the user can also input a filter string directly, though this has not been implemented here.

You should copy these samples to a working folder on your system, and then review how they work and experiment with your own modifications. A number of Python concepts are demonstrated, including a filtered list comprehension, slicing, several styles of iteration and print statements, and simple text file processing. The intention of these examples is simply to get you started. Python is a very rich language and the possibilities are limitless.

In all cases we use the Python argparse class to provide consistent use of the command line. for example, running:

python ChanAdd.py -h

will display the command line help for the ChanAdd.py script.

You will see that all scripts will import gx.geosoft as gx, and a GX context is obtained by calling gx.GXContext.create(). Most calls into the GX API will require the GX copntext to be provided as the first argument.

The GX API also includes many constants, and you will see examples of obtaining and using these constants in these sample files.

Note that some GX methods need to pass back a simple immutable data value (string, boolean, integer or float) by reference, but passing by reference is not possible in Python. For these situations, the GX API provides a set of simple classes which can be used to pass a mutable value that can be shared between the caller and the called function. Search for "immutable values by reference" in the on-line documentation for more information.

And finally, we include source code for all Geosoft GX tools as part of the GX Developer package. You can use these for reference to see how more complicated things are achieved in a GX, and the Python code will be very similar.