Skip to content

Describe levels of Op equality#94

Merged
gselzer merged 16 commits intomainfrom
scijava/scijava-ops-api/package-info
Nov 16, 2023
Merged

Describe levels of Op equality#94
gselzer merged 16 commits intomainfrom
scijava/scijava-ops-api/package-info

Conversation

@gselzer
Copy link
Member

@gselzer gselzer commented Oct 26, 2023

@gselzer gselzer added the documentation Improvements or additions to documentation label Oct 26, 2023
@gselzer gselzer requested review from ctrueden and hinerm October 26, 2023 18:32
@gselzer gselzer self-assigned this Oct 26, 2023
@@ -0,0 +1,46 @@
/**
* This module contains the API necessary to retrieve, execute, and reason about Ops.
* <h1>What is an Op?</h1>
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We talked recently about writing up the "philosophy of Ops" or some such, to explain the purpose of the library, design goals, etc. Perhaps this javadoc block would be a good place to put that? There is some material in that direction at https://imagej.net/libs/imagej-ops. I don't love that page though; I think we could do a better job describing the intent of the library from a broader and more easily understood perspective.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I wrote a little more, aligned with the bullets in https://imagej.net/libs/imagej-ops, in d723b0e. Let me know what you think @ctrueden

* <li> filter.gauss(ij.ImagePlus, java.lang.Double) -> ij.ImagePlus</li>
* <li> filter.gauss(net.imglib2.img.Img, net.imglib2.algorithm.neighborhood.Shape) -> net.imglib2.img.Img</li>
* </ol>
* Ops 1 and 2 should be considered form-equivalent, as they have the same name, and structural-equivalent, as they both take in an image data structure and a floating point number and return an image data structure, but they are likely not result-equivalent due to the underlying data structures.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

should be consideredare

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Does the fact that the number is a floating point number matter for structural equivalence? I.e.: where are we drawing the line with simplification? Number? Real number?

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

they are likely not result-equivalent due to the underlying data structuresthey may not be result-equivalent, for reasons such as implementation differences between the two algorithms, or precision loss when converting between data structures

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

floating point number matter for structural equivalence? I.e.: where are we drawing the line with simplification? Number? Real number?

I think simplification comes down to "what simplify Ops exist for some concrete type" such as Double or DoubleType

Fixed the other two issues in 4b19d77

* <p>
* Ops 1 and 3 should also be considered form-equivalent, as they have the same name, but are not structural-equivalent, as one computes its own Shape over which to perform a gaussian blur, while the other takes a predefined shape.
* <p>
* These definitions of equivalence provide a level of flexibility impossible without the Ops API; structural-equivalence allows us to, for example, define equivalent Ops across programming languages and libraries, and then to create scripts that can run unaltered on data types from each of those languages and libraries. Given the same {@link org.scijava.ops.api.OpEnvironment} and inputs, however, we ensure result-equivalence and therefore reproducability
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This last paragraph should be rewritten. Here is a suggestion:

These definitions of equivalence provide clarity when articulating the Ops framework's various benefits:

  1. The ops simplification mechanism enables structural-equivalent ops to be collapsed into a common simplified form, usable with appropriate data structures across programming languages and libraries.
  2. ... [out of time to write more today, sorry, but hopefully you see where I'm going with this]

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@ctrueden I think this is pretty tricky, but I gave it a go in ed64b87. Let me know what you think.

@gselzer gselzer force-pushed the scijava/scijava-ops-api/package-info branch from ed64b87 to 87e4759 Compare November 7, 2023 21:29
@gselzer gselzer force-pushed the scijava/scijava-ops-api/package-info branch from 87e4759 to f8eda92 Compare November 16, 2023 19:30
@gselzer gselzer merged commit 1def1bc into main Nov 16, 2023
@gselzer gselzer deleted the scijava/scijava-ops-api/package-info branch November 16, 2023 19:37
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

documentation Improvements or additions to documentation

Projects

No open projects

Development

Successfully merging this pull request may close these issues.

Document equality/equivalence semantics

2 participants