Installation

This section will guide you through the process of installing the CIMantic Graphs library, either from from PyPI or by cloning the git repository and building the wheel using Poetry.

Prerequisites

Before you start, make sure you have a python environment with:

Use of CIM-Graph with external databases, such as Neo4J and GraphDB requires installation of those databases using the recommended instructions from the database provider. A sample Docker file is provided in the CIM-Graph github to pull the databases with the correct configuration. Use of a database is not strictly required by CIM-Graph.

Installating from PyPi

To install the library directly from PyPI, you can use pip. Follow these steps:

  1. Open your terminal.

  2. Run the following command to install the library:

pip install cim-graph

Installing from Source

Installing Poetry

Poetry is a tool for dependency management and packaging in Python. It allows you to declare the libraries your project depends on and it will manage (install/update) them for you. Poetry offers a lockfile to ensure repeatable installs, and can build your project for distribution.

All tools in the PNNL-CIM-Tools family use Poetry for distribution and packaging.

To install Poetry, do NOT use the pypi installer. Instead, use the official cli installer:

  • In Linux, MacOS, WSL2:

curl -sSL https://install.python-poetry.org | python3 -

  • In Windows Powershell:

(Invoke-WebRequest -Uri https://install.python-poetry.org -UseBasicParsing).Content | py -

After running the cli installer, add Poetry to your default path using

  • In Linux, WSL2:

echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bash_profile
echo 'export PATH="$PATH:~/.local/share/pypoetry/venv/bin"' >> ~/.bashrc
source ~/.bashrc

  • In Windows PowerShell

[System.Environment]::SetEnvironmentVariable("Path", $env:Path + ";$env:APPDATA\pypoetry\venv\Scripts", [System.EnvironmentVariableTarget]::User)

  • In MacOS:

echo 'export PATH="$PATH:~/Library/Application Support/pypoetry/venv/bin"' >> ~/.bash_profile
source ~/.bash_profile

You can verify the installation by running

poetry --version

Finally, set the the poetry virtual environment to be created inside the repository by running

poetry config virtualenvs.in-project true

Cloning the Repository

To clone the repository, follow these steps:

  1. Open your terminal.

  2. Navigate to the directory where you want to clone the repository.

  3. Clone the repository by running the following command:

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

If you wish to clone a specific branch, you can specify it with the -b option:

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

Building a Virtual Environment and Wheel

After cloning the repository, change directories into CIM-Builder by running

cd CIM-Graph

Build the lock file with all requirements needed by running

poetry lock

This will also create a python virtual environment in ./CIM-Builder/.venv. To install CIM-Builder and all dependencies, run

poetry install

To use your local CIM-Builder library from other virtual environments, build the wheel and then pip install it from the other environment:

poetry build
cd ..
source ./my_other_env/.venv/bin/activate
pip install -e CIM-Graph