adding signac diff functionality

[atravitz]

Description

compares two or more jobs, returns jobs ids with only their keys that are not shared by all other jobs.

Motivation and Context

several requests for this functionality, often when two state points only vary by one or two values.

Resolves #248.

Types of Changes

• Documentation update
• Bug fix
• New feature
• Breaking change¹

¹The change breaks (or has the potential to break) existing functionality.

Checklist:

• I am familiar with the Contributing Guidelines.
• I agree with the terms of the Contributor Agreement.
• My name is on the list of contributors.
• My code follows the code style guideline of this project.
• The changes introduced by this pull request are covered by existing or newly introduced tests.

If necessary:

• I have updated the API documentation as part of the package doc-strings.
• I have created a separate pull request to update the framework documentation on signac-docs and linked it here.
• I have updated the changelog.

[vyasr]

Discussion on the appropriate scope and API of this PR is happening at #248. Once everything there is finalized we can update this PR.

[bdice]

I will make a couple commits to this branch to add proper docs.

[bdice]

Reviewers @vyasr @cbkerr and author @atravitz: I made some final touch-ups to this PR, and I am satisfied with the feature's quality and completeness for merging to master. I will be making a release tomorrow afternoon, probably around 5pm. If you have any review comments, it would be great to hear those and incorporate any needed changes before then.

[vyasr]

I tested the performance, for 10,000 jobs with a trivial statepoint ({'i': i} for i in range(int(1e4))) the diff took less than a second. For 100,000 jobs it can take a while to just open all the jobs (perhaps many minutes depending on whether any of them are in the FS cache and the nature of the filesystem), but the diffing itself is less than ten seconds, so my concerns about performance aren't too significant IMO. No need for progressbars.

[vyasr]

Regarding the different use-cases outlined in #248, I think the existing API is sufficiently general to allow this. We would simply need to add an extra argument to the Python and CLI such as diff_by that would default to statepoint (which I think is the sensible default for diffing jobs). The output would be of the same form, except that if we chose to diff files the leaf nodes of the dict would probably have to be a list of files instead of a mapping of key-value pairs. Document and data diffing should be transparently supported using the same API and output structure.

[atravitz]

suggestions from @vyasr have been addressed

[vyasr]

Very nearly there! Just a few very small changes.