Conversation
scijava/scijava-ops-api/src/main/java/org/scijava/ops/api/package-info.java
Outdated
Show resolved
Hide resolved
scijava/scijava-ops-api/src/main/java/org/scijava/ops/api/package-info.java
Outdated
Show resolved
Hide resolved
scijava/scijava-ops-api/src/main/java/org/scijava/ops/api/package-info.java
Outdated
Show resolved
Hide resolved
| @@ -0,0 +1,46 @@ | |||
| /** | |||
| * This module contains the API necessary to retrieve, execute, and reason about Ops. | |||
| * <h1>What is an Op?</h1> | |||
There was a problem hiding this comment.
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.
There was a problem hiding this comment.
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. |
There was a problem hiding this comment.
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?
There was a problem hiding this comment.
they are likely not result-equivalent due to the underlying data structures → they may not be result-equivalent, for reasons such as implementation differences between the two algorithms, or precision loss when converting between data structures
There was a problem hiding this comment.
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
scijava/scijava-ops-api/src/main/java/org/scijava/ops/api/package-info.java
Outdated
Show resolved
Hide resolved
scijava/scijava-ops-api/src/main/java/org/scijava/ops/api/package-info.java
Outdated
Show resolved
Hide resolved
scijava/scijava-ops-api/src/main/java/org/scijava/ops/api/package-info.java
Outdated
Show resolved
Hide resolved
| * <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 |
There was a problem hiding this comment.
This last paragraph should be rewritten. Here is a suggestion:
These definitions of equivalence provide clarity when articulating the Ops framework's various benefits:
- 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.
- ... [out of time to write more today, sorry, but hopefully you see where I'm going with this]
ed64b87 to
87e4759
Compare
Thanks @hinerm for the suggestions!
And similar changes
87e4759 to
f8eda92
Compare
Closes scijava/scijava#36