2.7 KiB

Raw Blame History

Aliasing

Status

ACCEPTED

Discussed by Alex Black and Paul Dubs on 05. March 2020.

Context

The API surface area is very large over all those namespaces. For consistency with our previous manually created API we want to be able to alias ops into different namespaces. Those aliases are meant as a convenience for users, so they can find ops more easily.

Decision

We introduce an aliasing mechanism Alias(NamespaceName().op("opName")) at the Namespace level, which can reference an op directly.

When an op is aliased like that, all of that ops signatures will be available in the referencing namespace. However, they will get an additional note in their documentation saying that it is an alias to the original op. In addition, the implementation of an alias signature, is a direct call of the same signature in the original namespace.

It is not allowed to alias an op from a namespace that only has it because it has aliased it itself.

When the requested op is not part of the given namespace, trying to alias it will throw an OpNotFoundException.

Example

Definitions

fun BaseOps() = Namespace("BaseOps"){
    Op("mmul") {
        javaPackage = "org.nd4j.linalg.api.ops.impl.reduce"
        Input(NUMERIC, "x") { description = "First input variable" }
        Input(NUMERIC, "y") { description = "Second input variable" }
        Arg(BOOL, "transposeX") { description = "Transpose x (first argument)"; defaultValue=false }
        Arg(BOOL, "transposeY") { description = "Transpose y (second argument)"; defaultValue=false }
        Arg(BOOL, "transposeZ") { description = "Transpose result array"; defaultValue=false }
        Output(NUMERIC, "output"){ description = "" }
        Doc(Language.ANY, DocScope.ALL){
            """
                Matrix multiplication: out = mmul(x,y)
                Supports specifying transpose argument to perform operation such as mmul(a^T, b), etc.
            """.trimIndent()
        }
    }
}

fun Linalg() = Namespace("Linalg"){
    Alias(BaseOps(), "mmul")
}

Output

This output is meant as a possible example. It is not what it will look like exactly once this feature is implemented.

public class Linalg{
    /**
     * Matrix multiplication: out = mmul(x,y)<br>
     * Supports specifying transpose argument to perform operation such as mmul(a^T, b), etc. <br>
     * 
     * Alias of basepackage.baseOps.mmul(x, y)<br>
     * 
     * @param x First input variable
     * @param y Second input variable
     */
    public static INDArray mmul(INDArray x, INDArray y){
        return basepakage.baseOps.mmul(x,y);
    }
}

Consequences

Advantages

We can make the API more flexible by allowing ops to be available from other namespaces

Disadvantages

The API becomes more crowded

2.7 KiB Raw Blame History