#### 3.1Dimension Systems

 (require punctaffy/hypersnippet/dim) package: punctaffy-lib

##### 3.1.1Dimension Systems in General

 procedure(dim-sys? v) → boolean? v : any/c
 procedure v : any/c
 value
Structure type property operations for dimension systems. These are systems of operations over a space of dimension numbers which can be used to describe the degree of a hypersnippet.

 procedure ds : dim-sys?
Returns a flat contract which recognizes any dimension number of the given dimension system.

 procedure(dim-sys-dim-max ds arg ...) → (dim-sys-dim/c ds) ds : dim-sys? arg : (dim-sys-dim/c ds)
Returns the maximum of zero or more dimension numbers.

The maximum of zero dimension numbers is well-defined; it’s the least dimension number of the dimension system. Typically this is 0, representing the dimension of 0-dimensional shapes. We recommend to use dim-sys-dim-zero in that case for better clarity of intent.

 procedure(dim-sys-dim-zero ds) → (dim-sys-dim/c ds) ds : dim-sys?
Returns the least dimension numbers of the dimension system. Typically this is 0, representing the dimension of 0-dimensional shapes.

This is equivalent to calling dim-sys-dim-max without passing in any dimension numbers. We provide this alternative for better clarity of intent.

 procedure(dim-sys-dim-max-of-two ds a b) → (dim-sys-dim/c ds) ds : dim-sys? a : (dim-sys-dim/c ds) b : (dim-sys-dim/c ds)
Returns the maximum of two given dimension numbers.

This is equivalent to calling dim-sys-dim-max without exactly two dimension numbers. We provide this alternative to clarify how make-dim-sys-impl-from-max-of-two works. It may also be good for catching errors.

 procedure(dim-sys-dim
 procedure(dim-sys-dim<=? ds a b) → boolean? ds : dim-sys? a : (dim-sys-dim/c ds) b : (dim-sys-dim/c ds)
 procedure(dim-sys-dim=? ds a b) → boolean? ds : dim-sys? a : (dim-sys-dim/c ds) b : (dim-sys-dim/c ds)
Compares the two given dimension numbers, returning whether they’re in strictly ascending order (less than), weakly ascending order (less than or equal), or equal.

 procedure(dim-sys-dim=0? ds d) → boolean? ds : dim-sys? d : (dim-sys-dim/c ds)
Returns whether the given dimension number is equal to 0 (in the sense of dim-sys-dim-zero).

 procedure(dim-sys-dim
 procedure(dim-sys-dim=/c ds bound) → flat-contract? ds : dim-sys? bound : (dim-sys-dim/c ds)
Returns a flat contract which recognizes dimension numbers which are strictly less than the given one, or which are equal to the given one.

 procedure ds : dim-sys?
Returns a flat contract which recognizes dimension numbers which are nonzero, in the sense of dim-sys-dim-zero.

procedure

 (make-dim-sys-impl-from-max-of-two dim/c dim=? dim-zero dim-max-of-two)
dim-sys-impl?
dim/c : (-> dim-sys? flat-contract?)
dim=? :
 (->i ( [ds dim-sys?] [a (ds) (dim-sys-dim/c ds)] [b (ds) (dim-sys-dim/c ds)]) [_ boolean?])
dim-zero : (->i ([ds dim-sys?]) [_ (ds) (dim-sys-dim/c ds)])
dim-max-of-two :
 (->i ( [ds dim-sys?] [a (ds) (dim-sys-dim/c ds)] [b (ds) (dim-sys-dim/c ds)]) [_ (ds) (dim-sys-dim/c ds)])
Given implementations for dim-sys-dim/c, dim-sys-dim=?, dim-sys-dim-zero, and dim-sys-dim-max-of-two, returns something a struct can use to implement the prop:dim-sys interface.

The given method implementations should observe some algebraic laws. Namely, the dim=? operation should be a decision procedure for equality of dimension numbers, and the dim-max-of-two operation should be associative, commutative, and idempotent with dim-zero as its identity element.

##### 3.1.2Category-Theoretic Dimension System Manipulations

 procedure v : any/c
 procedure v : any/c
 value : (struct-type-property/c dim-sys-morphism-sys-impl?)
Structure type property operations for structure-preserving transformations from one dimension system’s dimension numbers to another’s. In particular, these preserve relatedness of dimension numbers under the dim-sys-dim=? and dim-sys-dim-max operations.

 procedure dsms : dim-sys-morphism-sys?
Returns a dim-sys-morphism-sys? value’s source dimension system.

procedure

 (dim-sys-morphism-sys-replace-source dsms new-s)
dim-sys-morphism-sys?
dsms : dim-sys-morphism-sys?
new-s : dim-sys?
Returns a dim-sys-morphism-sys? value like the given one, but with its source dimension system replaced with the given one. This may raise an error if the given value isn’t similar enough to the one being replaced. This is intended only for use by dim-sys-morphism-sys/c and similar error-detection systems as a way to replace a value with one that reports better errors.

 procedure dsms : dim-sys-morphism-sys?
Returns a dim-sys-morphism-sys? value’s target dimension system.

procedure

 (dim-sys-morphism-sys-replace-target dsms new-s)
dim-sys-morphism-sys?
dsms : dim-sys-morphism-sys?
new-s : dim-sys?
Returns a dim-sys-morphism-sys? value like the given one, but with its target dimension system replaced with the given one. This may raise an error if the given value isn’t similar enough to the one being replaced. This is intended only for use by dim-sys-morphism-sys/c and similar error-detection systems as a way to replace a value with one that reports better errors.

 procedure → (dim-sys-dim/c (dim-sys-morphism-sys-target ms)) ms : dim-sys-morphism-sys? d : (dim-sys-dim/c (dim-sys-morphism-sys-source ms))
Transforms a dimension number according to the given dim-sys-morphism-sys? value.

procedure

 (make-dim-sys-morphism-sys-impl-from-morph source replace-source target replace-target morph-dim)
dim-sys-morphism-sys-impl?
source : (-> dim-sys-morphism-sys? dim-sys?)
replace-source : (-> dim-sys-morphism-sys? dim-sys? dim-sys-morphism-sys?)
target : (-> dim-sys-morphism-sys? dim-sys?)
replace-target : (-> dim-sys-morphism-sys? dim-sys? dim-sys-morphism-sys?)
morph-dim :
 (->i ( [ms dim-sys-morphism-sys?] [object (ms) (dim-sys-dim/c (dim-sys-morphism-sys-source ms))]) [_ (ms) (dim-sys-dim/c (dim-sys-morphism-sys-target ms))])
Given implementations for the following methods, returns something a struct can use to implement the prop:dim-sys-morphism-sys interface.

When the replace methods don’t raise errors, they should observe the lens laws: The result of getting a value after it’s been replaced should be the same as just using the value that was passed to the replacer. The result of replacing a value with itself should be the same as not using the replacer at all. The result of replacing a value and replacing it a second time should be the same as just skipping to the second replacement.

Moreover, the replace methods should not raise an error when a value is replaced with itself. They’re intended only for use by dim-sys-morphism-sys/c and similar error-detection systems, which will tend to replace a replace a value with one that reports better errors.

The other given method implementation (dim-sys-morphism-sys-morph-dim) should observe some algebraic laws. Namely, it should preserve the relatedness of dimension numbers by the dim-sys-dim=? and dim-sys-dim-max operations (not to mention operations like dim-sys-dim-zero, which are derived from those). In more symbolic terms (using a pseudocode DSL):

 (#:for-all ms dim-sys-morphism-sys? #:let s (dim-sys-morphism-sys-source ms) #:let t (dim-sys-morphism-sys-target ms) (#:should-be-equal (morph-dim ms (dim-sys-dim-zero s)) (dim-sys-dim-zero t))) (#:for-all ms dim-sys-morphism-sys? #:let s (dim-sys-morphism-sys-source ms) #:let t (dim-sys-morphism-sys-target ms) a (dim-sys-dim/c s) b (dim-sys-dim/c s) (#:should-be-equal (morph-dim ms (dim-sys-dim-max s a b)) (dim-sys-dim-max t (morph-dim ms a) (morph-dim ms b)))) (#:for-all ms dim-sys-morphism-sys? #:let s (dim-sys-morphism-sys-source ms) #:let t (dim-sys-morphism-sys-target ms) a (dim-sys-dim/c s) b (dim-sys-dim/c s) (#:should-be-equal (dim-sys-dim=? s  a b) (dim-sys-dim=? t (morph-dim ms a) (morph-dim ms b))))

 procedure(dim-sys-morphism-sys/c source/c target/c) → contract? source/c : contract? target/c : contract?
Returns a contract that recognizes any dim-sys-morphism-sys? value whose source and target dimension systems are recognized by the given contracts.

The result is a flat contract as long as the given contracts are flat.

 procedure(dim-sys-morphism-sys-identity endpoint) → (dim-sys-morphism-sys/c (ok/c endpoint) (ok/c endpoint)) endpoint : dim-sys?
Returns the identity dim-sys-morphism-sys? value on the given dimension system. This is a transformation that goes from the given dimension system to itself, taking every dimension number to itself.

procedure

 (dim-sys-morphism-sys/c (ok/c (dim-sys-morphism-sys-source ab)) (ok/c (dim-sys-morphism-sys-target bc)))
ab : dim-sys-morphism-sys?
bc :
 (dim-sys-morphism-sys/c (ok/c (dim-sys-morphism-sys-target ab)) any/c)
Returns the composition of the two given dim-sys-morphism-sys? values. This is a transformation that goes from the first transformation’s source dimension system to the second transformation’s target dimension system, transforming every dimension number by applying the first transformation and then the second. The target of the first transformation should match the source of the second.

This composition operation is written in diagrammatic order, where in the process of reading off the arguments from left to right, we proceed from the source to the target of each transformation. Composition is often written with its arguments the other way around (e.g. in Racket’s compose operation).

 syntax
 syntax
 match expander
 procedure v : any/c
Struct-like operations which construct and deconstruct a lathe-morphisms/in-fp/category category (category-sys?) where the objects are dimension systems and the morphisms are structure-preserving transformations between them (namely, dim-sys-morphism-sys? values).

Every two dim-sys-category-sys values are equal?. One such value is always an ok/c match for another.

procedure

 (functor-from-dim-sys-sys-apply-to-morphism fs dsms)

 (category-sys-morphism/c (functor-sys-target fs) (functor-sys-apply-to-object fs (dim-sys-morphism-sys-source dsms)) (functor-sys-apply-to-object fs (dim-sys-morphism-sys-target dsms)))
fs : (functor-sys/c dim-sys-category-sys? any/c)
dsms : dim-sys-morphism-sys?
Uses the given lathe-morphisms/in-fp/category functor to transform a dim-sys-morphism-sys? value.

This is equivalent to (functor-sys-apply-to-morphism fs (dim-sys-morphism-sys-source dsms) (dim-sys-morphism-sys-target dsms) dsms).

procedure

 (natural-transformation-from-from-dim-sys-sys-apply-to-morphism nts dsms)

 (category-sys-morphism/c (natural-transformation-sys-endpoint-target nts) (functor-sys-apply-to-object (natural-transformation-sys-source nts) (dim-sys-morphism-sys-source dsms)) (functor-sys-apply-to-object (natural-transformation-sys-target nts) (dim-sys-morphism-sys-target dsms)))
nts :
 (natural-transformation-sys/c dim-sys-category-sys? any/c any/c any/c)
dsms : dim-sys-morphism-sys?
Uses the given lathe-morphisms/in-fp/category natural transformation to transform a dim-sys-morphism-sys? value.

This is equivalent to (natural-transformation-sys-apply-to-morphism fs (dim-sys-morphism-sys-source dsms) (dim-sys-morphism-sys-target dsms) dsms).

 procedure v : any/c
Returns whether the given value is a lathe-morphisms/in-fp/category functor from the category (dim-sys-category-sys) to itself.

procedure

 (make-dim-sys-endofunctor-sys-impl-from-apply apply-to-dim-sys apply-to-dim-sys-morphism-sys)
functor-sys-impl?
apply-to-dim-sys : (-> dim-sys-endofunctor-sys? dim-sys? dim-sys?)
apply-to-dim-sys-morphism-sys :
 (->i ( [es dim-sys-endofunctor-sys?] [ms dim-sys-morphism-sys?]) [_ (es ms) (dim-sys-morphism-sys/c (ok/c (functor-sys-apply-to-object es (dim-sys-morphism-sys-source ms))) (ok/c (functor-sys-apply-to-object es (dim-sys-morphism-sys-target ms))))])
Given implementations for the following methods, returns something a struct can use to implement the prop:functor-sys interface in a way that makes it satisfy dim-sys-endofunctor-sys?.

These method implementations should observe the same algebraic laws as those required by make-functor-sys-impl-from-apply.

This is essentially a shorthand for calling make-functor-sys-impl-from-apply and supplying the appropriate source- and target-determining method implementations.

##### 3.1.3Commonly Used Dimension Systems

 syntax
 syntax
 match expander
 procedure v : any/c
Struct-like operations which construct and deconstruct a dimension system (dim-sys?) where the dimension numbers are the natural? numbers and the dim-sys-dim-max operation is max.

The dim-sys-dim/c of a nat-dim-sys is a flat contract.

Every two nat-dim-sys values are equal?. One such value is always an ok/c match for another.

 syntax
 syntax(extended-with-top-dim-finite original)
 match expander(extended-with-top-dim-finite original)
 procedure v : any/c
 procedure d : extended-with-top-dim-finite?
Struct-like operations which construct and deconstruct an extended-with-top-dim? value that represents one of the original dimension numbers of a dimension system that was extended with an infinite dimension number.

Two extended-with-top-dim-finite values are equal? if they contain equal? elements.

 syntax
 syntax
 match expander
 procedure v : any/c
Struct-like operations which construct and deconstruct an extended-with-top-dim? value that represents the infinite dimension number of a dimension system that was extended with one.

Every two extended-with-top-dim-infinite values are equal?.

 procedure v : any/c
Returns whether the given value is a dimension number of a dimension system that was extended with an infinite dimension number. That is, it checks that the value is either an extended-with-top-dim-finite? value or an extended-with-top-dim-infinite? value.

 procedure(extended-with-top-dim/c original-dim/c) → contract? original-dim/c : contract?
Returns a contract that recognizes an extended-with-top-dim? value where the unextended dimension system’s corresponding dimension number, if any, abides by the given contract.

The resulting contract has the same contract obstinacy as the given one.

 procedure(extended-with-top-dim=? original-dim=? a b) → boolean? original-dim=? : (-> any/c any/c boolean?) a : extended-with-top-dim? b : extended-with-top-dim?
Returns whether the two given extended-with-top-dim? values are equal, given a function for checking whether two dimension numbers of the unextended dimension system are equal.

If the given function is not the decision procedure of a decidable equivalence relation, then neither is this one. In that case, this one merely relates two finite dimension numbers if they would be related by original-dim=? in the unextended dimension system.

 syntax

syntax

(extended-with-top-dim-sys original)

 original : dim-sys?
 match expander(extended-with-top-dim-sys original)
 procedure v : any/c
 procedure ds : extended-with-top-dim-sys?
Struct-like operations which construct and deconstruct a dimension system (dim-sys?) where the dimension numbers are (extended-with-top-dim/c (dim-sys-dim/c original)) values. That is to say, the dimension numbers are all the dimension numbers of the original dimension system (wrapped in extended-with-top-dim-finite) and one more dimension number greater than the rest (extended-with-top-dim-infinite).

The resulting dimension system’s dim-sys-dim-max operation corresponds with the original operation on the extended-with-top-dim-finite? dimension numbers, and it treats the extended-with-top-dim-infinite? dimension number as being greater than the rest.

Two extended-with-top-dim-sys values are equal? if they contain equal? elements. One such value is an ok/c match for another if the first’s element is ok/c for the second’s.

 syntax

syntax

(extended-with-top-dim-sys-morphism-sys original)

 original : dim-sys-morphism-sys?
 match expander(extended-with-top-dim-sys-morphism-sys original)
 procedure v : any/c
 procedure → dim-sys-morphism-sys? dsms : extended-with-top-dim-sys-morphism-sys?
Struct-like operations which construct and deconstruct a dim-sys-morphism-sys? value where the source and target are extended-with-top-dim-sys? values and the action on finite dimension numbers is the given dim-sys-morphism-sys?. In other words, this transforms extended-with-top-dim? values by transforming their extended-with-top-dim-finite-original values, if any.

Two extended-with-top-dim-sys-morphism-sys values are equal? if they contain equal? elements. One such value is an ok/c match for another if the first’s element is ok/c for the second’s.

 syntax
 syntax
 match expander
 procedure v : any/c
Struct-like operations which construct and deconstruct a lathe-morphisms/in-fp/category functor-sys? value where the source and target categories are both (dim-sys-category-sys) and the action on morphisms is extended-with-top-dim-sys-morphism-sys. In other words, this value represents the transformation-transforming functionality of extended-with-top-dim-sys-morphism-sys together with the assurance that its meta-transformation respects the compositional laws of the object-transformations the way a functor does.

Every two extended-with-top-dim-sys-morphism-sys values are equal?. One such value is always an ok/c match for another.

 syntax

syntax

 source : dim-sys?
 match expander
 procedure v : any/c
 procedure dsms : extend-with-top-dim-sys-morphism-sys?
Struct-like operations which construct and deconstruct a dim-sys-morphism-sys? value where the source is any dim-sys? value and the target is a corresponding dim-sys? made by extended-with-top-dim-sys. The action on dimension numbers is extended-with-top-dim-finite. In other words, this transforms dimension numbers by transporting them to their corresponding elements in a dimension system that has been extended with an additional number greater than all the others. (No dimension number from the source is transported to the additional number in the target.)

Two extend-with-top-dim-sys-morphism-sys values are equal? if they contain equal? elements. One such value is an ok/c match for another if the first’s element is ok/c for the second’s.

 syntax

syntax

(extended-with-top-finite-dim-sys original)

 original : dim-sys?
 match expander(extended-with-top-finite-dim-sys original)
 procedure v : any/c
 procedure ds : extended-with-top-dim-sys?
Struct-like operations which construct and deconstruct a dimension system (dim-sys?) where the dimension numbers are all the dimension numbers of the original dimension system wrapped in extended-with-top-dim-finite, and where the action on those dimension numbers is the same as the original action. That is to say, this is a dimension system that represents its dimension numbers the same way extended-with-top-dim-sys does, but which doesn’t actually include the additional extended-with-top-dim-infinite dimension number.

This is primarily used as the source of unextend-with-top-dim-sys, which otherwise would have to have an error-handling case if it encountered the extended-with-top-dim-infinite value. (TODO: Consider passing an error handler to unextend-with-top-dim-sys-morphism-sys. Perhaps that would be a better approach than this, since we would be encouraged to write errors where the error messages make the most sense, not rely indirectly on the error messages of the contracts of the behaviors we invoke. On the other hand, perhaps that error-handling should take place in a morphism (or natural transformation) from extended-with-top-dim-sys to extended-with-top-finite-dim-sys.)

Two extended-with-top-finite-dim-sys values are equal? if they contain equal? elements. One such value is an ok/c match for another if the first’s element is ok/c for the second’s.

 syntax

syntax

 target : dim-sys?
 match expander
 procedure v : any/c
 procedure dsms : extend-with-top-dim-sys-morphism-sys?
Struct-like operations which construct and deconstruct a dim-sys-morphism-sys? value where the source is an extended-with-top-finite-dim-sys? dimension system and the target is the dimension system it’s based on. The action on dimension numbers is to unwrap their extended-with-top-dim-finite wrappers.

Note that the source is an extended-with-top-finite-dim-sys? value, not an extended-with-top-dim-sys? value, so this operation can’t encounter a extended-with-top-dim-infinite value and get stuck.

Two extend-with-top-dim-sys-morphism-sys values are equal? if they contain equal? elements. One such value is an ok/c match for another if the first’s element is ok/c for the second’s.