Environment Variables

IMPORTANT: As of v0.3+, the ConnectionParameters class has been deprecated. Use the environment variables below to authenticate with the database.

The CIM-Graph library supports multiple databases. The environment variables specify how to read the CIM model:

Required environment variables:

  • CIMG_CIM_PROFILE: CIM profile module name

Optional environment variables:

If these values are not specified, they will default to the sample values listed in example.env

  • CIMG_NAMESPACE: CIM namespace, default is "http://iec.ch/TC57/CIM100#"

  • CIMG_IEC61970_301: Serialization version. Versions 7(default) and below use rdf:ID=. Version 8 uses rdf:about=urn:uuid:

  • CIMG_URL: URL at which the database can be reached via TCP/IP or other connection

  • CIMG_HOST: Database host address

  • CIMG_PORT: Database host port

  • CIMG_DATABASE: Database name

  • CIMG_USERNAME: Database username

  • CIMG_PASSWORD: Database password

Note that not all parameters are required. Each database connection uses a subset of these arguments depending on the requirements of the database connection driver.

CIMG_CIM_PROFILE

This specifies the specific version of CIM to be used, based on the available python data profiles loaded into the library.

The value used should match the name CIM profile classes module imported using import cimgraph.data_profile.profile_name as cim.

The environment variable should be specified as a string and can use shorthand for the profile name or the full library path. A full path to separate library can also be used.

The value can be retrieved using the get_cim_profile() method from the CIM-Graph databases module.

Example 1

The example below shows how to set and retrieve the CIM profile using the short name of the profile

[1]:

import os
# Set environment variable
os.environ['CIMG_CIM_PROFILE'] = 'cim17v40'

[2]:

from cimgraph.databases import get_cim_profile
# Retrieve value of env var and library module path
cim_profile, cim = get_cim_profile()

Example 2

The example below shows how to set and retrieve the CIM profile using the full path of the profile

[3]:

# Set environment variable
os.environ['CIMG_CIM_PROFILE'] = 'cimgraph.data_profile.rc4_2021'
# Retrieve value of env var and library module path
cim_profile, cim = get_cim_profile()

CIMG_NAMESPACE

This environment variable sets the namespace tied to the cim: prefix.

Each version of the CIM uses a specific namespace, which can typically be found in the first line of the XML file, such as

xmlns:cim="http://iec.ch/TC57/2011/CIM-schema-cim15#"

The default used by CIMantic Graphs is the CIM100 namespace "http://iec.ch/TC57/CIM100#" used by CIM 17.

The value can be retrieved from the .get_namespace() method in the databases module.

Example 1

The code snippet below shows how to retrieve the default namespace

[4]:

from cimgraph.databases import get_namespace
default_namespace = get_namespace()
print(default_namespace)

http://iec.ch/TC57/CIM100#

Example 2

To set a custom namespace, set the environment variable to the full namespace URL:

[9]:

# Set the new namespace
os.environ['CIMG_NAMESPACE'] = "http://iec.ch/TC57/2011/CIM-schema-cim15#"
# Clear cached namespace
get_namespace.cache_clear()
# Retrieve the new namespace
namespace = get_namespace()
print(namespace)

http://iec.ch/TC57/2011/CIM-schema-cim15#

CIMG_IEC61960_301

This environment variable tracks the serialization format and use of underscores as part of the rdf identifier of each object. The default value in CIM-Graph 0.3+ is 8 (no underscores).

Versions 7.0 and older of the IEC 61970-301 standard use the serialization format based on rdf:ID and a leading underscore:

<cim:ClassName rdf:ID="_ABEB635F-729D-24BF-B8A4-E2EF268D8B9E">
  <cim:ClsName.Association rdf:resource="#_73C512BD-7249-4F50-50DA-D93849B89C43"/>
</cim:ClassName>

Version 8.0 of the standard has changed the serialization format to specify that the serialization identifier must be a UUID, with no underscore:

<cim:ClassName rdf:about="urn:uuid:abeb635f-729d-24bf-b8a4-e2ef268d8b9e">
  <cim:ClassName.Association rdf:resource="urn:uuid:73c512bd-7249-4f50-50da-d93849b89c43"/>
</cim:ClassName>

If your model file contains underscores, use

os.environ['CIMG_IEC61970_301'] = '7'

If your model does not contain underscores, use

os.environ['CIMG_IEC61970_301'] = '8'

Example 1

The code snippet below shows how to retrieve the default serialization version.

[10]:

from cimgraph.databases import get_iec61970_301
version = get_iec61970_301()
print(version)

8

Example 2

The code snippet below shows how to change to serialization environment variable to indicate that the mRIDs have underscores:

[11]:

# Set the new namespace
os.environ['CIMG_IEC61970_301'] = '7'
# Clear cached namespace
get_iec61970_301.cache_clear()
# Retrieve the new namespace
namespace = get_iec61970_301()
print(namespace)

7

Connection Parameters (Deprecated)

Older versions of CIM-graph (0.1.x and 0.2.x) used the ConnectionParameters class to specify the variables needed to connect to the database

The first step in using any of CIMantic Graphs functionalities is to define the connection parameters, which specify the CIM Profile, serialization format, and database to be used. The ConnectionParameters class is used to specify these inputs with the following required and optional arguments: