Installation¶

This guide will walk you through installing CIMantic Graphs either from PyPI or from source using UV.

Prerequisites¶

Before you start, make sure you have:

• Python 3.10+ - Download Python
• pip - Included with Python 3.4+

Optional: External Databases¶

CIMantic Graphs can work with several external databases:

• Blazegraph - RDF triple store
• Neo4j - Graph database
• GraphDB - RDF database
• MySQL - Relational database

These databases are optional - CIMantic Graphs can also work with local files (XML, JSON-LD, RDF) without any database.

A sample Docker Compose file is provided in the CIM-Graph repository to quickly set up the databases with correct configurations:

docker-compose up -d

Installing from PyPI¶

The easiest way to install CIMantic Graphs is from PyPI using pip:

pip install cim-graph

To install with development dependencies:

pip install cim-graph[dev]

Verify Installation¶

After installation, verify it works:

In [ ]:

import cimgraph
import cimgraph.data_profile.rc4_2021 as cim

# Create a simple CIM object
breaker = cim.Breaker(name="test_breaker", open=False)
print(f"Created breaker: {breaker.name}")
print(f"Status: {'Open' if breaker.open else 'Closed'}")

import cimgraph import cimgraph.data_profile.rc4_2021 as cim # Create a simple CIM object breaker = cim.Breaker(name="test_breaker", open=False) print(f"Created breaker: {breaker.name}") print(f"Status: {'Open' if breaker.open else 'Closed'}")

---

Installing from Source¶

For development or to use the latest unreleased features, you can install from source using UV.

Why UV?¶

UV is a fast Python package installer and resolver written in Rust. It's:

• 10-100x faster than pip
• Drop-in replacement for pip and pip-tools
• Built-in virtual environment management
• Reproducible installs with lock files

CIMantic Graphs uses UV as its primary build tool.

Installing UV¶

Install with pip¶

pip install uv

Verify UV is installed:

uv --version

---

Clone the Repository¶

First, clone the CIM-Graph repository:

git clone https://github.com/PNNL-CIM-Tools/CIM-Graph.git
cd CIM-Graph

To clone a specific branch (e.g., develop):

git clone https://github.com/PNNL-CIM-Tools/CIM-Graph.git -b develop
cd CIM-Graph

---

Install with UV¶

UV automatically creates a virtual environment and installs all dependencies.

Basic Installation¶

Install CIMantic Graphs and all dependencies:

uv sync

This command:

1. Creates a virtual environment in .venv/ (if it doesn't exist)
2. Installs all dependencies from pyproject.toml
3. Installs CIMantic Graphs in editable mode

Install with Development Dependencies¶

To also install development tools (pytest, pre-commit, etc.):

uv sync --extra dev

Or use the shorthand:

uv sync --all-extras

---

Activate the Virtual Environment¶

After running uv sync, activate the virtual environment:

Linux, macOS, and WSL2¶

source .venv/bin/activate

Windows PowerShell¶

.venv\Scripts\Activate.ps1

Windows Command Prompt¶

cmd
.venv\Scripts\activate.bat

You should see (.venv) at the beginning of your command prompt.

---

Common UV Commands¶

Here are some useful UV commands for working with CIMantic Graphs:

Add a New Dependency¶

uv add <package-name>

Add a Development Dependency¶

uv add --dev <package-name>

Update Dependencies¶

uv sync --upgrade

Run a Command in the Virtual Environment¶

uv run python script.py
uv run pytest

Build Distribution Packages¶

uv build

This creates wheel and source distribution in dist/ directory.

Install Built Package Elsewhere¶

After building, you can install the wheel in another environment:

# From another environment
pip install /path/to/CIM-Graph/dist/cim_graph-0.4.3a8-py3-none-any.whl

---

Verify Source Installation¶

After installing from source, verify everything works:

In [ ]:

# Run this after activating your virtual environment
import cimgraph
import cimgraph.data_profile.cimhub_2023 as cim

# Test creating objects
substation = cim.Substation(name="Test Substation")
breaker = cim.Breaker(name="Breaker 1", open=False)
breaker.EquipmentContainer = substation

print(f"Substation: {substation.name}")
print(f"Breaker: {breaker.name}")
print(f"Breaker container: {breaker.EquipmentContainer.name}")

# Run this after activating your virtual environment import cimgraph import cimgraph.data_profile.cimhub_2023 as cim # Test creating objects substation = cim.Substation(name="Test Substation") breaker = cim.Breaker(name="Breaker 1", open=False) breaker.EquipmentContainer = substation print(f"Substation: {substation.name}") print(f"Breaker: {breaker.name}") print(f"Breaker container: {breaker.EquipmentContainer.name}")

---

Next Steps¶

Now that you have CIMantic Graphs installed, you can:

1. Learn the library structure - See Structure
2. Connect to databases - See Databases Overview
3. Work with CIM profiles - See Profiles Overview
4. Build graph models - See Graph Models
5. Try the Quick Start - See Overview

Common Issues¶

ModuleNotFoundError: No module named 'cimgraph'

• Make sure you activated the virtual environment
• Try running uv sync again

UV command not found

• Add UV to your PATH or restart your terminal
• Try reinstalling UV

Import errors with dependencies

• Run uv sync --upgrade to update all dependencies
• Check that you have Python 3.10 or higher

---