{ "cells": [ { "cell_type": "markdown", "metadata": {}, "source": [ "# Environment Variables" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "**IMPORTANT: As of v0.3+, the ConnectionParameters class has been deprecated. Use the environment variables below to authenticate with the database.**\n", "\n", "The CIM-Graph library supports multiple databases. The environment variables specify how to read the CIM model:\n", "\n", "__Required environment variables:__\n", "\n", "* `CIMG_CIM_PROFILE`: CIM profile module name\n", "\n", "__Optional environment variables:__\n", "\n", "If these values are not specified, they will default to the sample values listed in [example.env](https://github.com/PNNL-CIM-Tools/CIM-Graph/blob/develop/example.env)\n", "\n", "* `CIMG_NAMESPACE`: CIM namespace, default is `\"http://iec.ch/TC57/CIM100#\"`\n", "\n", "* `CIMG_IEC61970_301`: Serialization version. Versions 7(default) and below use `rdf:ID=`. Version 8 uses `rdf:about=urn:uuid:`\n", "\n", "* `CIMG_URL`: URL at which the database can be reached via TCP/IP or other connection\n", "\n", "* `CIMG_HOST`: Database host address\n", "\n", "* `CIMG_PORT`: Database host port\n", "\n", "* `CIMG_DATABASE`: Database name\n", "\n", "* `CIMG_USERNAME`: Database username\n", "\n", "* `CIMG_PASSWORD`: Database password\n", "\n", "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." ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "----" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "## CIMG_CIM_PROFILE\n", "\n", "This specifies the specific version of CIM to be used, based on the available python data profiles loaded into the library. \n", "\n", "The value used should match the name CIM profile classes module imported using `import cimgraph.data_profile.profile_name as cim`.\n", "\n", "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.\n", "\n", "The value can be retrieved using the `get_cim_profile()` method from the CIM-Graph databases module." ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "##### Example 1\n", "\n", "The example below shows how to set and retrieve the CIM profile using the short name of the profile" ] }, { "cell_type": "code", "execution_count": 1, "metadata": {}, "outputs": [], "source": [ "import os\n", "# Set environment variable\n", "os.environ['CIMG_CIM_PROFILE'] = 'cim17v40'" ] }, { "cell_type": "code", "execution_count": 2, "metadata": {}, "outputs": [], "source": [ "from cimgraph.databases import get_cim_profile\n", "# Retrieve value of env var and library module path\n", "cim_profile, cim = get_cim_profile()" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "##### Example 2\n", "\n", "The example below shows how to set and retrieve the CIM profile using the full path of the profile" ] }, { "cell_type": "code", "execution_count": 3, "metadata": {}, "outputs": [], "source": [ "# Set environment variable\n", "os.environ['CIMG_CIM_PROFILE'] = 'cimgraph.data_profile.rc4_2021'\n", "# Retrieve value of env var and library module path\n", "cim_profile, cim = get_cim_profile()" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "----" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "### CIMG_NAMESPACE\n", "\n", "This environment variable sets the namespace tied to the `cim:` prefix.\n", "\n", "Each version of the CIM uses a specific namespace, which can typically be found in the first line of the XML file, such as\n", "\n", "`xmlns:cim=\"http://iec.ch/TC57/2011/CIM-schema-cim15#\"`\n", "\n", "The default used by CIMantic Graphs is the CIM100 namespace `\"http://iec.ch/TC57/CIM100#\"` used by CIM 17.\n", "\n", "The value can be retrieved from the `.get_namespace()` method in the databases module." ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "##### Example 1\n", "\n", "The code snippet below shows how to retrieve the default namespace" ] }, { "cell_type": "code", "execution_count": 4, "metadata": {}, "outputs": [ { "name": "stdout", "output_type": "stream", "text": [ "http://iec.ch/TC57/CIM100#\n" ] } ], "source": [ "from cimgraph.databases import get_namespace\n", "default_namespace = get_namespace()\n", "print(default_namespace)" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "##### Example 2\n", "\n", "To set a custom namespace, set the environment variable to the full namespace URL:" ] }, { "cell_type": "code", "execution_count": 9, "metadata": {}, "outputs": [ { "name": "stdout", "output_type": "stream", "text": [ "http://iec.ch/TC57/2011/CIM-schema-cim15#\n" ] } ], "source": [ "# Set the new namespace\n", "os.environ['CIMG_NAMESPACE'] = \"http://iec.ch/TC57/2011/CIM-schema-cim15#\"\n", "# Clear cached namespace\n", "get_namespace.cache_clear()\n", "# Retrieve the new namespace\n", "namespace = get_namespace()\n", "print(namespace)" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "----" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "## CIMG_IEC61960_301\n", "\n", "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).\n", "\n", "Versions 7.0 and older of the IEC 61970-301 standard use the serialization format based on `rdf:ID` and a leading underscore:\n", "\n", "```xml\n", "\n", " \n", "\n", "```\n", "\n", "Version 8.0 of the standard has changed the serialization format to specify that the serialization identifier must be a UUID, with no underscore:\n", "\n", "```xml\n", "\n", " \n", "\n", "```" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "If your model file contains underscores, use \n", "\n", "```python\n", "os.environ['CIMG_IEC61970_301'] = '7'\n", "```\n", "\n", "If your model does **not** contain underscores, use\n", "\n", "```python\n", "os.environ['CIMG_IEC61970_301'] = '8'\n", "```\n" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "##### Example 1\n", "\n", "The code snippet below shows how to retrieve the default serialization version." ] }, { "cell_type": "code", "execution_count": 10, "metadata": {}, "outputs": [ { "name": "stdout", "output_type": "stream", "text": [ "8\n" ] } ], "source": [ "from cimgraph.databases import get_iec61970_301\n", "version = get_iec61970_301()\n", "print(version)" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "##### Example 2\n", "\n", "The code snippet below shows how to change to serialization environment variable to indicate that the mRIDs have underscores:" ] }, { "cell_type": "code", "execution_count": 11, "metadata": {}, "outputs": [ { "name": "stdout", "output_type": "stream", "text": [ "7\n" ] } ], "source": [ "# Set the new namespace\n", "os.environ['CIMG_IEC61970_301'] = '7'\n", "# Clear cached namespace\n", "get_iec61970_301.cache_clear()\n", "# Retrieve the new namespace\n", "namespace = get_iec61970_301()\n", "print(namespace)" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "----" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "## Connection Parameters (Deprecated)" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "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\n", "\n", "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:" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "----" ] } ], "metadata": { "kernelspec": { "display_name": ".venv", "language": "python", "name": "python3" }, "language_info": { "codemirror_mode": { "name": "ipython", "version": 3 }, "file_extension": ".py", "mimetype": "text/x-python", "name": "python", "nbconvert_exporter": "python", "pygments_lexer": "ipython3", "version": "3.10.12" } }, "nbformat": 4, "nbformat_minor": 2 }