cimsi 0.7.8.dev1__py3-none-any.whl

cimsi-0.7.8.dev1.dist-info/METADATA

@@ -0,0 +1,80 @@
+Metadata-Version: 2.4
+Name: cimsi
+Version: 0.7.8.dev1
+Summary: Integrated Modelling System Infrastructure (IMSI) is a comprehensive software project used to download, configure, build and run the suite of models in the CCCma Integrated Modelling System.
+Author: CCCma Technical Development Team
+License: OGL-Canada-2.0
+Project-URL: Homepage, https://imsi.readthedocs.io/en/latest/
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Natural Language :: English
+Classifier: Programming Language :: Python :: 3.10
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: isodate
+Requires-Dist: cftime
+Requires-Dist: xarray
+Requires-Dist: dataclasses
+Requires-Dist: json5
+Requires-Dist: click
+Requires-Dist: pydantic
+Requires-Dist: omegaconf
+Requires-Dist: pandas
+Requires-Dist: rich
+Requires-Dist: pyarrow
+Requires-Dist: python-dotenv
+Requires-Dist: questionary
+Provides-Extra: tests
+Requires-Dist: coverage; extra == "tests"
+Requires-Dist: pytest; extra == "tests"
+Requires-Dist: python-dotenv; extra == "tests"
+Provides-Extra: docs
+Requires-Dist: sphinxcontrib-programoutput; extra == "docs"
+Requires-Dist: sphinx-rtd-theme==1.2.2; extra == "docs"
+Requires-Dist: recommonmark; extra == "docs"
+
+# Integrated Modelling System Infrastructure (IMSI)
+
+[![Documentation Status](https://readthedocs.org/projects/imsi/badge/?version=latest)](https://imsi.readthedocs.io/en/latest/?version=latest)
+![Pipeline Status](https://gitlab.com/cccma/imsi/badges/main/pipeline.svg)
+![Coverage Status](https://gitlab.com/cccma/imsi/badges/main/coverage.svg)
+
+The **Integrated Modelling System Infrastructure (IMSI)** is a comprehensive Python-based package used to download, configure, build, and run the suite of models in the CCCma Integrated Modelling System.
+
+- **Documentation:** [https://imsi.readthedocs.io](https://imsi.readthedocs.io)
+
+---
+
+## License
+
+- [Open Government License – Canada version 2.0](https://open.canada.ca/en/open-government-licence-canada)
+
+---
+
+## Installation
+
+IMSI is normally pre-installed on support machines by technical staff, and users need only source an environment.
+
+You can install IMSI manually as shown below. It is recommended to install it inside a Python or Conda virtual environment.
+
+```bash
+python3 -m venv /path/to/new/virtual/environment 
+source /path/to/new/virtual/environment/activate
+# conda create -n imsi-test python=3.10
+
+git clone git@gitlab.science.gc.ca:CanESM/imsi.git
+cd imsi
+pip install .      # for usage
+# pip install -e . # for development
+```
+
+## Basic usage
+```bash
+imsi -h # for help
+
+# Setup a CanESM5.1 p1 CMIP6 piControl run
+imsi setup --repo=https://gitlab.com/cccma/canesm --ver=develop_canesm --exp=cmip6-piControl --model=canesm51_p1 --runid=imsi-test
+imsi build          # compile executables
+imsi save-restarts  # save desired restarts
+imsi submit         # submit the run
+```

cimsi-0.7.8.dev1.dist-info/RECORD

@@ -0,0 +1,95 @@
+imsi/__init__.py,sha256=CaHq_QzgjiRVGD5xLxa81QskILsYDU-EgVo_x_JvAaA,496
+imsi/_version.py,sha256=3t1HsJwtnDc9GSerNbHdL7BeBdC4V_klOT6ZdE7VErw,717
+imsi/imsi.site.rc,sha256=YyeEmw3-V0ZQkUrhwfuAydY7kwaTagKBXu1ulaVAu8A,133
+imsi/cli/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+imsi/cli/cli_snapshot_state.sh,sha256=4sEC4gzl4TBcNUwrUmVcaLQTkA9us-Fhro7Tl5DL2YA,4321
+imsi/cli/core_cli.py,sha256=UscNpTfmx1f4Ae1a_5n0FSA76ucFrjr-P9AhaucZqMk,10192
+imsi/cli/core_tracking.py,sha256=JqFIleaaQOrv9szLXUsHRjwSxPu_DVoFO5mkQ0giPHA,5619
+imsi/cli/entry.py,sha256=8rBtvbzlsOPF7o-wBDzSEvpoqn8hzfPohdzPa9uQIO4,2419
+imsi/cli/lazy.py,sha256=BMgOYRR5uKXFG7VKw0I5cCb67nIDwy_o43nRAa0vtro,3374
+imsi/cli/post_install.py,sha256=PbsXBV7PH7ZrAtIcnM9JCqEDMfCnnR9jg5kA-l6BFqk,722
+imsi/cli/sectioned_group.py,sha256=qtGcxYQVWcZ3gG49h1ABjoZ8lCV8vKnmDejtaXB6qFk,894
+imsi/config_manager/.gitignore,sha256=1q4ouJ43KTPNGKKrRWzdM8DLGKa86y0ToGr2WE7R_5U,104
+imsi/config_manager/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+imsi/config_manager/config_manager.py,sha256=1dELI4mgB_8P5EakH7qeEaL_aQ4a82rkhPKCjrbgyHg,21036
+imsi/config_manager/databases.py,sha256=d9mFe1Fod6AQ1jCzRPK7NK6fOLTvUtKNvMSzhrIMf6U,5021
+imsi/config_manager/tests.py,sha256=jhxMR_YJFv2ZldzZh8q33-T4LM4m7hF2NRKkuC7jX3k,1998
+imsi/config_manager/schema/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+imsi/config_manager/schema/compiler.py,sha256=Z6h3mIFsJ-n3-kRXeafs9rq29_tGVulFcN7ZslEppOw,174
+imsi/config_manager/schema/components.py,sha256=3zG4lg5QBSlO3vhRT1FmhI6Xb4hFIqbUcvmBQLc5R_g,3460
+imsi/config_manager/schema/experiment.py,sha256=byfqGdJUXtyuMgf454pyDieezY4nXp6UJyg3AXKABog,1145
+imsi/config_manager/schema/machine.py,sha256=6h9Ulpz88bGjdVSMu-DM2Ycu1RdrhGux0lE4QWqjvWs,6413
+imsi/config_manager/schema/model.py,sha256=eoghmp6bX2_cOn3SlELI82pjUGYTnAZj9tOQTn-n7CM,681
+imsi/config_manager/schema/post_processing.py,sha256=crU2_5qAhW9jKUHHNWleXD-xI0reP__q7AuU1FP56Oo,471
+imsi/config_manager/schema/sequencing.py,sha256=VXcAczn-HxWF3pyGVdLuvqEQARg0X9PZzmr3DX1kyfg,983
+imsi/config_manager/schema/setup_params.py,sha256=fsXjtxSCWbT77V_dgviM28DgBd6vpRlvT6drz5TtxvY,166
+imsi/config_manager/schema/types.py,sha256=3NGkjBaoa1MZ5Hx5Y6XarHkLg8bbsxaVDk0L8XvmwF8,250
+imsi/config_manager/schema/utilities.py,sha256=XLn9Yo2TcrYi-mKdauzIHpZR-9ooFPDJXO7Ci9dedVE,250
+imsi/scheduler_interface/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+imsi/scheduler_interface/scheduler_tools.py,sha256=L6hVHMGPebj9R56It4EzFTOj_xAxlFxfuv7SD8c43Qo,3229
+imsi/scheduler_interface/schedulers.py,sha256=fENYJtBK-0i9sxAscFxfHxUiMkbjX7KLc0gPYVHKQZY,6236
+imsi/sequencer_interface/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+imsi/sequencer_interface/iss_cap.py,sha256=AnGgVBjpdtjABkFJ1HtqHf-v_1JBEFfaqpZqVgw0fuE,9616
+imsi/sequencer_interface/maestro_cap.py,sha256=4JoW0NTZ-5f_9YeKMdqS6xmHueKBuhU16pqdh0t2wEQ,51014
+imsi/sequencer_interface/maestro_status.py,sha256=oltycJ5GPm-fwftg0JGHWJ40RTnFy6mnB509c2pXLjM,8295
+imsi/sequencer_interface/sequencers.py,sha256=8SAsk-a2H9ezlQmIkrlFzJsVqIZWUFQqsD7U0pU2Yag,2414
+imsi/shell_interface/__init__.py,sha256=kQgA-PEDA8zccCcZCJD6DS0yc7OPf4AvqQCnS7Fnzd0,370
+imsi/shell_interface/config_hooks_collection.py,sha256=O3M_xlLzAiW50anizKzBNSNOwlIzxpXo65OBSpdopvQ,5151
+imsi/shell_interface/config_hooks_collection_config.yaml,sha256=xKPIHAeZ7g-uS9DQiJYbvnmgIpIq5iAravG0BXVSdww,190
+imsi/shell_interface/config_hooks_manager.py,sha256=L2oon5zUmplVseVwWMlCOvawySctB37xB4ftycCUjIo,3248
+imsi/shell_interface/parse_dbs_example.py,sha256=q3HVcAAMqbdBEsnEGBziUFvhJzuxqcktCO64E57D_fE,1807
+imsi/shell_interface/shell_comp_environment.py,sha256=qqVortr5TxrBj9HBZp7C9HTI7veiUJMXeoidjeVzE_g,6873
+imsi/shell_interface/shell_config_parameters.py,sha256=A0PHJEZC9qT-k7hkR0yPz-PDKjxs0h8EUJse7bykz2c,5708
+imsi/shell_interface/shell_diag_parameters.py,sha256=7-wIPWeBsM4XXSZPzjSWZMX_aLhXuhSi34zE-OE7V3k,1572
+imsi/shell_interface/shell_inputs_outputs.py,sha256=hqA5B2lmwg6-GlF15S1HsKq5ynJlVAXE5B8z0z0PPm4,9181
+imsi/shell_interface/shell_interface_manager.py,sha256=3_TYQMxl7Ei7j9cbD835Wj_biwv3Xip-CvE5iLDQXkE,8338
+imsi/shell_interface/shell_interface_utilities.py,sha256=0UBVgY2bK3HC3z-C086Q667wtdlvfwI_BV0FDXujkiQ,1246
+imsi/shell_interface/shell_timing_vars.py,sha256=KXye_l_dWtb5YUppZZPpY4a6ziwjChDNqf_vl2y3pGU,3866
+imsi/tools/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+imsi/tools/disk_tools/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+imsi/tools/disk_tools/disk_tools.py,sha256=Yh7tfGeCx9yeXHjNL5dQzIQpCQmW6pNfSCqr9sD5yys,2915
+imsi/tools/disk_tools/disk_tools_cli.py,sha256=HeIbVnttG2YL8LRxX69YAhuac-8WDbkJJrF1-xtAOcI,1051
+imsi/tools/ensemble/README.md,sha256=b1-HFagG5MuDQMLN4ds2YDy2BbP3I2orKCfxkS9QoR8,6391
+imsi/tools/ensemble/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+imsi/tools/ensemble/all_supported_exp.yaml,sha256=LhcqW2lre52tfEO37cul8cyJ4M2dyEkkxWWPCcL3vVg,1661
+imsi/tools/ensemble/config.py,sha256=MxpnhrNJt-lfwXa0BMzVXd2bmXYA0yWoiVBaLfe4Rmg,1731
+imsi/tools/ensemble/config.yaml,sha256=VHyuqpSl7CUoLRIryI3Hg2VxTjs7s8odkXYBTTgOONY,285
+imsi/tools/ensemble/ensemble_cli.py,sha256=4hzwQdaU7836c5hM8lPfzIqUgRRsbr1UMNEFm3ODSFI,3114
+imsi/tools/ensemble/ensemble_manager.py,sha256=3-FswugoKoNFi2J7IOaS41FXwxpmfHc3J7pY3APZTQ4,9250
+imsi/tools/ensemble/config/example_table.csv,sha256=fxS0g6fmWrYvpdbNMlTl0M_Y1cFJ6K9CSVLqR9EhStU,82
+imsi/tools/ensemble/config/example_table.yaml,sha256=WMLppQgU6hVHRPCse44OxYBwqkSaQt470rcpteEql3A,338
+imsi/tools/ensemble/table_utils/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+imsi/tools/ensemble/table_utils/data_model.py,sha256=YIT7IIDSN0NXaKeZk3OpoeGxwkFR4F252UyONM4jfyY,4379
+imsi/tools/ensemble/table_utils/table_model.py,sha256=T-5ARkK5C_X8d51UFFXq2ffsPrZZSIY6iEJ-9DFR0Wo,7154
+imsi/tools/ensemble/table_utils/table_utils.py,sha256=uL2ic4mdEinYAcukObQPJ-qJdhJeP_vs1VreYueo5K8,5659
+imsi/tools/list/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+imsi/tools/list/list_cli.py,sha256=SLd_id-r5lvYY319VJTsKMdln_QrNzdxcinSOhwBrfw,4327
+imsi/tools/list/list_manager.py,sha256=nNzSkHz6mdzei2qR2-KB4Wumt3dJ57ia55BdQG279s8,3548
+imsi/tools/menu/menu_cli.py,sha256=hmi8ns0y5dwFNIf5mjkcTYpE762gazbsGcdIVeHu15Q,1958
+imsi/tools/menu/menu_helpers.py,sha256=370pSve9P03B0n1_GpHPgWYqapuwu3bASWDiUf2UsSs,2927
+imsi/tools/simple_sequencer/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+imsi/tools/simple_sequencer/iss.py,sha256=o2NmaofxPyg-qDt7KxeHUWJjd_L5RthaRPXMlFvO7WU,33264
+imsi/tools/simple_sequencer/iss_cli.py,sha256=GXzZaUpOR7N2Vlx-3luj6f59oCnyAjwuMJsljXO-6oo,9575
+imsi/tools/simple_sequencer/iss_globals.py,sha256=i8FtxbLcAIUMoE-nHRlZiEiGqC9evl1g6BV4TgvY_Wo,5009
+imsi/tools/time_manager/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+imsi/tools/time_manager/cftime_utils.py,sha256=JLroGw9SlhI6swtnOnG_aGnJx-_NB7A2e3Uiqq0INWw,11824
+imsi/tools/time_manager/chunk_manager.py,sha256=DGyVzuqYfGi1M9_bNoTHxY4p015np1BmmKd1DkjT7OI,14622
+imsi/tools/time_manager/time_manager.py,sha256=MZSaMRBzTc8qCsT1xEw6-S-wtQubpwN_TktQZhtaZjU,12667
+imsi/tools/time_manager/timer_cli.py,sha256=BQvfGG0xaVP_hLbJYcXZ5IvMXJnNraWLO4c1mPGp6JI,7750
+imsi/tools/validate/validate_cli.py,sha256=Z-ODRv4OoWcAJJXd-hbI0Ud8AcnwgYyQlNBEX9rFHcc,4649
+imsi/user_interface/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+imsi/user_interface/setup_manager.py,sha256=Jp2nNqcUcQMwFwiJzCLsjsUjoWyAGqzig4BBIlPc72w,10844
+imsi/user_interface/ui_manager.py,sha256=E3QuU_l3_TRR7qPAySwyGae1ZStcqUgtGvAVbgoUjhY,12722
+imsi/user_interface/ui_utils.py,sha256=HtqyBM6KcBXIYAR4uD1LkopphlnRxXEIBq8qyxm3GXM,4182
+imsi/utils/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+imsi/utils/dict_tools.py,sha256=VXpYl1uM35KgP_rHaJQ7PtLKFJ5HLjeME0dYj-PXByI,12607
+imsi/utils/general.py,sha256=wNBRiUctMzlSjs6h6UclscEC9U2FUzJ0rugfBmY2CO8,4481
+imsi/utils/git_tools.py,sha256=mFZ3RXy7-VsqB6QwNj3WUQ2Po6X07IoTSQ48BheIs_4,6804
+imsi/utils/multiple_inheritance_test.py,sha256=TgtHzfs2vp6Um5mm2np8eI581ADpfSMuZJSk2z0QV7I,2549
+imsi/utils/nml_tools.py,sha256=W-zWJQm69tJ1-tIOB3KNIJP6-aUr0Q8WbN7E003PYYA,7127
+imsi/utils/repo_query_status.sh,sha256=Jh1u1X1GSpQCwG0wORTh4Oms8j5F-3oFKxLlaxworEM,836
+cimsi-0.7.8.dev1.dist-info/METADATA,sha256=v7aNFP8d5tkeRH2GH7RoXp5Tn5gE59KdoUdgzK8klyc,2908
+cimsi-0.7.8.dev1.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+cimsi-0.7.8.dev1.dist-info/entry_points.txt,sha256=HshtKQr9HaQXBJ7XERdsFjO2kpiW__wSZIqOwhg_Xks,99
+cimsi-0.7.8.dev1.dist-info/top_level.txt,sha256=w8iJC9Bv_SLu8L5zqVJ_egupI0KoJ8K0pg0TVmVnzkQ,5
+cimsi-0.7.8.dev1.dist-info/RECORD,,

cimsi-0.7.8.dev1.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (80.9.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

cimsi-0.7.8.dev1.dist-info/entry_points.txt

@@ -0,0 +1,3 @@
+[console_scripts]
+imsi = imsi.cli.entry:cli
+imsi-post-install = imsi.cli.post_install:post_install

cimsi-0.7.8.dev1.dist-info/top_level.txt

@@ -0,0 +1 @@
+imsi

imsi/__init__.py

@@ -0,0 +1,16 @@
+"""Top-level package for imsi."""
+
+__author__ = "CCCma Technical Development Team"
+__email__ = ""
+
+from importlib.metadata import version as get_version, PackageNotFoundError
+
+try:
+    # Use installed package version (when installed via pip)
+    __version__ = get_version("cimsi")
+except PackageNotFoundError:
+    try:
+        # Use locally generated setuptools_scm file (for local dev)
+        from ._version import version as __version__
+    except ImportError:
+        __version__ = "unknown"

imsi/_version.py

@@ -0,0 +1,34 @@
+# file generated by setuptools-scm
+# don't change, don't track in version control
+
+__all__ = [
+    "__version__",
+    "__version_tuple__",
+    "version",
+    "version_tuple",
+    "__commit_id__",
+    "commit_id",
+]
+
+TYPE_CHECKING = False
+if TYPE_CHECKING:
+    from typing import Tuple
+    from typing import Union
+
+    VERSION_TUPLE = Tuple[Union[int, str], ...]
+    COMMIT_ID = Union[str, None]
+else:
+    VERSION_TUPLE = object
+    COMMIT_ID = object
+
+version: str
+__version__: str
+__version_tuple__: VERSION_TUPLE
+version_tuple: VERSION_TUPLE
+commit_id: COMMIT_ID
+__commit_id__: COMMIT_ID
+
+__version__ = version = '0.7.8.dev1'
+__version_tuple__ = version_tuple = (0, 7, 8, 'dev1')
+
+__commit_id__ = commit_id = None

imsi/cli/cli_snapshot_state.sh

@@ -0,0 +1,175 @@
+#!/bin/bash
+# create a "snapshot" of a git repo.
+# - write output from git commands to files
+# - keep the folder of those contents if they are unique
+#
+# usage: cli_snapshot_state.sh [list of rel paths]
+#
+# the paths are relative to the current path. the paths must be to git repos.
+# the state is capture for the git repo and any submodules if present.
+#
+# NOTE: this is an imsi integrated tool, and assumes certain processes and
+# states of execution upstream.
+#
+set -e
+
+bail() {
+    echo "$(basename $0) ERROR: $*"
+    exit 1
+}
+
+usage () {
+   echo "Usage: $0 -p <rel_path> [-i <run_dir>] [-o <out_dir>]"
+}
+
+help () {
+    usage
+    echo ""
+    echo "Arguments:"
+    echo "     -p <rel_path>"
+    echo "          Relative paths to <run_dir>. Must be git repo."
+    echo "          Multiple paths can be supplied by repeating -p."
+    echo ""
+    echo "Options:"
+    echo "     -i <run_dir>"
+    echo "          Input directory, usually run directory (default pwd)."
+    echo "     -o <out_dir>"
+    echo "          Parent path to where the log artefacts are written"
+    echo "          (as <out_dir>/.imsi/states) (default pwd)."
+    echo "     -h"
+    echo "          Display usage information."
+    echo ""
+}
+
+# defaults / init
+rel_paths=()
+run_dir=$(pwd)
+out_dir=$(pwd)
+
+# note: since this is an integrated imsi tool, pwd is usually the
+# work dir (runid) folder from where the imsi command is issued.
+# this should be left as-is for most applications.
+# other internal imsi tools may call this tool, which then would require
+# setting -i and -o explicitly.
+
+OPTSTRING=":p:i:o:h"
+
+while getopts ${OPTSTRING} opt; do
+    case $opt in
+        p)
+            rel_paths+=("$OPTARG")
+            ;;
+        i)
+            run_dir=${OPTARG}
+            ;;
+        o)
+            out_dir=${OPTARG}
+            ;;
+        h)
+            help
+            exit 0
+            ;;
+        :)
+            echo "Option -$OPTARG requires an argument." >&2
+            usage
+            exit 1
+            ;;
+        \?)
+            echo "Invalid option: -$OPTARG" >&2
+            usage
+            exit 1
+            ;;
+    esac
+done
+shift $((OPTIND-1))
+
+snapshot_git_state() {
+    local path
+    local log_prefix
+    local cwd
+    path=$1
+    log_prefix=$2
+    cwd=$(pwd)
+
+    if [[ -z $log_prefix ]]; then
+        log_prefix=""
+    else
+        log_prefix="${log_prefix}_"
+    fi
+
+    cd $path
+    mh=$(git rev-parse HEAD)
+    desc=$(git describe --always)
+    echo $path >> $tmp_dir/${log_prefix}rev.txt
+    echo $mh $(basename $path) "(${desc})" >> $tmp_dir/${log_prefix}rev.txt
+    git submodule status --recursive >> $tmp_dir/${log_prefix}rev.txt
+    git status --porcelain=v1 >> $tmp_dir/${log_prefix}status.txt
+    git diff --submodule=diff > $tmp_dir/${log_prefix}diff.diff
+    cd $cwd
+}
+
+is_git_repo() {
+    local path=$1
+    if [[ -d "${path}/.git" ]]; then
+        echo 1
+    else
+        echo 0
+    fi
+}
+
+#======================
+# prep
+#======================
+
+[[ -d $run_dir ]] || bail No directory $run_dir
+[[ -d $out_dir ]] || bail No directory $out_dir
+
+full_paths=( "${rel_paths[@]/#/$run_dir/}" )
+
+# validate
+for p in "${full_paths[@]}"; do
+    if [[ ! -d "${p}" ]]; then
+        bail $p is not a valid directory
+    fi
+    rc=$(is_git_repo "${p}")
+    if [ $rc == 0 ]; then
+        bail $p is not a git repo
+    fi
+done
+
+# create output folders
+log_dir=$out_dir/.imsi/states
+tmp_dir=$log_dir/tmp_state
+
+mkdir -p $tmp_dir
+
+#======================
+# snapshot
+#======================
+
+# iterate over the folders -- determine naming and snapshot state by
+# creating artefacts
+#   account for duplicate names by creating an id for the input folder path
+#   by combining the basename and (short) hash of its full folder path
+#  (assume this is deterministic)
+#  (the full file paths are written to the *rev.txt files for cross referencing)
+
+for p in ${full_paths[@]}; do
+    b=$(basename "$p")
+    p_id=$( echo $p | md5sum | cut -c1-7 )
+    b_id="${b}_${p_id}"
+    snapshot_git_state $p $b_id $run_dir
+done
+
+# hash the folder of the entire state
+hash=$(find $tmp_dir -type f -exec md5sum {} \; | sort -k 2 | md5sum | awk '{ print $1 }')
+
+if [ -d $log_dir/$hash ]; then
+    # if hash exists, remove the tmp_dir
+    rm -rf $tmp_dir
+else
+    # otherwise, save this new state
+    mv $tmp_dir $log_dir/$hash
+fi
+
+echo $hash