README.md

Evo Code Samples

Welcome to the Evo Python SDK code samples! This directory contains comprehensive Jupyter notebook examples that demonstrate how to use the various Evo APIs for geoscience data management and analysis.

📋 Prerequisites

• Evo app: You need a registered app in Bentley to obtain a client ID
• Python: Version 3.10 or higher
• Jupyter Environment: JupyterLab, VS Code, or another Jupyter notebook editor

🚀 Quick start

1. Register an Evo app

Register your Evo application in the Bentley Developer Portal to get your client credentials. If a member of your team has already registered an app, contact them and ask for the client credentials. For in-depth instructions, follow this guide on the Seequent Developer Portal.

a. In a new browser tab or window, visit https://developer.bentley.com/ and sign in.

b. Click your profile in the top-right corner and select My Apps. You may need to agree to Bentley developer terms before proceeding.

c. Click the dropdown arrow on the Register New button and choose Register new app for Seequent Evo.

d. Enter an application name and select the Native application type.

e. Enter http://localhost:3000/signin-callback in Redirect URIs.

f. Click Register.

g. The next screen displays the unique Client ID of your application. Save a copy - you will need it to run the Jupyter notebooks.

2. Obtain a local copy of this repository

If you want to focus on the code samples, or if you aren't comfortable using Git, download a copy of this repository as a ZIP file. Visit https://github.com/SeequentEvo/evo-python-sdk and follow the instructions below:

Alternatively, if you are comfortable using Git:

git clone https://github.com/SeequentEvo/evo-python-sdk.git

3. Set up your environment

You must first install the package manager uv that will make is easy to set up your Python environment.

Follow the instructions below for Windows, macOS or Linux.

Windows

1. Find the local copy of this repository in Windows Explorer. It will be called evo-python-sdk-main if you downloaded as a ZIP file.

2. Right-click on the folder and choose Open in Terminal.

   

3. Enter the following command to install uv.

   powershell -ExecutionPolicy Bypass -c "irm https://astral.sh/uv/$(Get-Content ./UV_VERSION)/install.ps1 | iex"

4. Move to the samples directory.

   cd samples

5. Install the Python dependencies.

   uv sync

macOS

1. Find the local copy of this repository in Finder. It will be called evo-python-sdk-main if you downloaded as a ZIP file.

2. Open the folder so that you can see it's contents.

3. On the Path bar at the bottom of the window, right-click on evo-python-sdk-main.

   HINT: If the Path bar isn't visible, select Show Path Bar from the View menu.

   

4. From the pop-up menu, select Open in Terminal.

   

5. Enter the following command from the root directory of the repository to install uv.

   ./scripts/install-uv.sh

6. Move to the samples directory.

   cd samples

7. Install the Python dependencies.

   uv sync

Linux

NOTE: This example is based on Ubuntu, but other Linux environments will operate in a similar way.

1. Find the local copy of this repository in Files. It will be called evo-python-sdk-main if you downloaded as a ZIP file.

2. Right-click on the folder and choose Open in Terminal.

   

3. Enter the following command from the root directory of the repository to install uv.

   ./scripts/install-uv.sh

4. Move to the samples directory.

   cd samples

5. Install the Python dependencies

   uv sync

4. Run the notebooks

Tip

Before running these notebooks, ensure that you have access to at least one Evo workspace. You can do this in two ways:

• Ask a colleague to add you to an existing workspace.

• Create a workspace by signing in to the Evo portal, opening the Workspaces tab, clicking the Create workspace button, and then following the instructions.

  

From the samples directory, launch Jupyter.

uv run jupyter notebook

Tip

If you are using VS Code or another Python IDE, simply open one of the .ipynb files.

Jupyter will list everything in the samples directory, and you can click to browse each section.

Before diving into the geoscience code samples, we recommend that you first test your Evo app to make sure your client credentials are set up correctly.

a. Click to open auth-and-evo-discovery. b. Click to open native-app-token.ipynb. c. Enter your client ID and callback URL from when you registered your Evo app.

d. Run the first code cell by pressing Shift+Enter or by pressing the Play button in the toolbar.

e. Run the next code cell. You may see red warning text - this is normal.

f. If everything is set up correctly, your web browser should open a new tab and ask you to sign in with your Bentley ID. Once you have signed in and granted access to the app, return to the tab with Jupyter running.

g. Using the widget that appears under the code cell, select your Organisation, Hub and Workspace.

h. Run the next code cell. You should see a printout of your Evo hub URL, organisation ID and workspace ID.

The values printed in the last cell are required for almost all Evo API calls. This is because all Evo data is stored in a workspace that exists in your assigned Evo hub and organisation.

Now that you know how Evo auth works, explore the other Jupyter notebooks. They all require your client ID and callback URL, just like in this example.

📚 Sample categories

🔐 Authentication & discovery

📁 auth-and-evo-discovery

Learn about Evo auth and the Evo Discovery service:

• native-app-token.ipynb - Authentication for desktop applications
• service-app-token.ipynb - Authentication for service applications
• evo-discovery.ipynb - Find your organization ID and hub URL

🧊 Block models

📁 blockmodels

Block model workflow examples using both SDK and direct API approaches:

• sdk-examples.ipynb - High-level Block Model SDK examples (recommended)
• api-examples.ipynb - Direct API calls for advanced use cases

These notebooks demonstrate:

• Creating regular block models
• Adding and updating columns
• Querying data with bounding boxes
• Working with PyArrow tables and pandas DataFrames

🗂️ File operations

📁 files

Basic unstructured file management operations:

• Upload files to Evo
• Download files from Evo
• List and organize files
• Delete files
• Bonus: Sample Python scripts for file Input-Output in Evo

🌍 Geoscience objects

📁 geoscience-objects

Publish and download various geoscience data types:

• Drilling campaigns and downhole collections
• Point sets and triangular meshes
• 2D regular grids
• Complex geoscience data structures

Note: Some notebooks have platform-specific requirements (e.g., Windows-only dependencies)

🏢 Workspace management

📁 workspaces

Administrative operations:

• Manage Evo workspaces
• Handle user roles and permissions
• Bonus: Move geoscience objects from one workspace to another

✨ Extras

📁 common-tasks

This section includes tasks that are common across many of the Evo APIs.

Advanced file processing:

• Working with Parquet data files
• Data manipulation

🔧 Running a sample

1. Open the notebook in your preferred editor.
2. Update the first cell with your client ID and callback URL.
3. Run the authentication cell - this will open your browser for Bentley ID sign-in.
4. Select your organisation, instance and workspace using the provided widget.
5. Continue with the remaining cells in order.

💡 Tips for success

• Always start with authentication: The auth-and-evo-discovery samples are the best place to get started.
• Check platform requirements: Some geoscience-objects samples are Windows-specific.
• Use virtual environments: Keep dependencies isolated for each project.
• Follow notebook order: Run cells sequentially for best results.
• Keep credentials secure: Never commit tokens or credentials to version control.

📖 Additional resources

• Seequent Developer Portal
• Seequent Community
• Evo Python SDK README

🆘 Getting help

If you encounter issues:

1. Check that you've completed the authentication setup.
2. Verify your Python version (3.10+).
3. Ensure all requirements are installed.
4. Visit the Seequent Community for support.
5. Check the GitHub issues for known problems.

Happy coding with Evo! 🎉