Add docs and address comments

Author: zdevito

docs/source/inference.rst

@@ -271,3 +271,20 @@ Strided indexing with dynamic stride
 The value of :code:`S(0)` is not fixed until runtime, so we can't resolve the
 size of :code:`A` or the range of the loop. This case throws a compile-time
 error. A :code:`where` clause that defines the range of :code:`i` is required.
+
+Constant fill using an exists clause
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. code::
+
+    def constant_fill(float(N) A, float c) -> B {
+      B(i) = c where A(i) exists
+    }
+
+An :code:`exists` clause allows you to add additional expressions to the range
+inference process without having the expressions affect the actual computation.
+In this example, it allows you to say that :code:`B(i)` should have the same size as
+:code:`A(i)`, but be filled with a constant value :code:`c`.  That is, you should infer the
+range of :code:`B(i)` to exist at all the places where :code:`A(i)` exists.
+It is equivalent to writing the expression :code:`true ? c : A(i)`, but with
+clearer intentions.

include/tc/lang/sema.h

@@ -369,7 +369,7 @@ struct Sema {
   TreeRef boolType(TreeRef anchor) {
     return c(TK_BOOL, anchor->range(), {});
   }
-  void checkDim(const Ident& dim) {
+  void checkDim(Ident dim) {
     insert(env, dim, dimType(dim), false);
   }
   TreeRef checkTensorType(TreeRef type) {
@@ -451,7 +451,7 @@ struct Sema {
     // where clauses are checked _before_ the rhs because they
     // introduce let bindings that are in scope for the rhs
     auto where_clauses_ = stmt.whereClauses().map(
-        [&](const TreeRef& rc) { return checkWhereClause(rc); });
+        [&](TreeRef rc) { return checkWhereClause(rc); });
 
     TreeRef rhs_ = checkExp(stmt.rhs(), true);
     TreeRef scalar_type = typeOfExpr(rhs_);
@@ -488,7 +488,7 @@ struct Sema {
     live_input_names.erase(stmt.ident().name());
 
     auto equivalent_statement_ =
-        stmt.equivalent().map([&](const Equivalent& eq) {
+        stmt.equivalent().map([&](Equivalent eq) {
           auto indices_ = eq.accesses().map(
               [&](TreeRef index) { return checkExp(index, true); });
           return Equivalent::create(eq.range(), eq.name(), indices_);
@@ -526,7 +526,7 @@ struct Sema {
 
     return result;
   }
-  bool isNotInplace(const TreeRef& assignment) {
+  bool isNotInplace(TreeRef assignment) {
     switch (assignment->kind()) {
       case TK_PLUS_EQ_B:
       case TK_TIMES_EQ_B:
@@ -567,15 +567,15 @@ struct Sema {
       throw ErrorReport(ident) << name << " already defined";
     }
   }
-  TreeRef lookup(const Ident& ident, bool required) {
+  TreeRef lookup(Ident ident, bool required) {
     TreeRef v = lookup(index_env, ident, false);
     if (!v)
       v = lookup(let_env, ident, false);
     if (!v)
       v = lookup(env, ident, required);
     return v;
   }
-  TreeRef lookup(Env& the_env, const Ident& ident, bool required) {
+  TreeRef lookup(Env& the_env, Ident ident, bool required) {
     std::string name = ident.name();
     auto it = the_env.find(name);
     if (required && it == the_env.end()) {

test/test_corner_cases.cc

@@ -79,73 +79,73 @@ static void Fail(
   }
 }
 
-TEST(FailTest, E1) {
+TEST(TestCornerCases, E1) {
   Fail("expected (", " def f{} {}", {}, {});
 }
-TEST(FailTest, E2) {
+TEST(TestCornerCases, E2) {
   Succeed("def f(float(1) a) -> (b) { b(i) = a(i) }", {F(1)}, {F(1)});
 }
 
 // free(): invalid next size (fast): 0x000000003b2d6230 ***
-TEST(FailTest, DISABLED_E4) {
+TEST(TestCornerCases, DISABLED_E4) {
   Succeed("def f(float a) -> (b) { b = a }", {F()}, {F()});
 }
 
 // main conflicts with program main in nvcc
-TEST(FailTest, DISABLED_E3) {
+TEST(TestCornerCases, DISABLED_E3) {
   Succeed(
       "def main(float(1) a) -> (b) { b(i) = a(i) }", {F(1)}, {F(1)}, "main");
 }
 
 // segfaults on line:
 // src/aten/aten_compiler.cc:123
 // 123    at::Backend backend = inputs[0].type().backend();
-TEST(FailTest, DISABLED_E5) {
+TEST(TestCornerCases, DISABLED_E5) {
   Succeed("def f() -> (b) { b(i) = 4 where i in 0:10 }", {}, {F(0)});
 }
 
-TEST(FailTest, E6) {
+TEST(TestCornerCases, E6) {
   Succeed("def f(float a) -> (b) { b(i) = a where i in 0:10 }", {F()}, {F(10)});
 }
 
-TEST(FailTest, E7) {
+TEST(TestCornerCases, E7) {
   Fail(
       "expected 2 inputs",
       "def f(float a, float c) -> (b) { b(i) = a where i in 0:10 }",
       {F()},
       {F(10)});
 }
 
-TEST(FailTest, E8) {
+TEST(TestCornerCases, E8) {
   Fail(
       "expected type int32",
       "def f(int32 a) -> (b) { b(i) = a where i in 0:10 }",
       {F()},
       {F(10)});
 }
 
-TEST(FailTest, E9) {
+TEST(TestCornerCases, E9) {
   Fail(
       "expected a tensor with 0",
       "def f(int32 a) -> (b) { b(i) = a where i in 0:10 }",
       {I(1, 2)},
       {F(10)});
 }
 
-TEST(FailTest, E10) {
+TEST(TestCornerCases, E10) {
   Succeed(
       "def f(int32 a) -> (b) { b(i) = a where i in 0:10 }", {I()}, {I(10, 10)});
 }
 
-TEST(FailTest, E11) {
+TEST(TestCornerCases, E11) {
   Fail(
       "expected integral type",
       "def f(int32(N) a) -> (b) { b(i) = a(i + .5) }",
       {I()},
       {I(10, 10)});
 }
 
-TEST(FailTest, E12) {
+TEST(TestCornerCases, E12) {
   // this test should eventually work when we can handle non-trivial
   // expressions in where clauses
   Fail(
@@ -155,7 +155,7 @@ TEST(FailTest, E12) {
       {I(10)});
 }
 
-TEST(FailTest, E13) {
+TEST(TestCornerCases, E13) {
   // this test is harder still, because the bounds of the output
   // depend on the non-trivial expression
   Fail(
@@ -165,7 +165,7 @@ TEST(FailTest, E13) {
       {I(10)});
 }
 
-TEST(FailTest, DISABLED_E14) {
+TEST(TestCornerCases, DISABLED_E14) {
   // Currently expressions in where clauses are assumed to be
   // affine. Needs fixing.
   Fail(
@@ -175,7 +175,7 @@ TEST(FailTest, DISABLED_E14) {
       {I(10)});
 }
 
-TEST(FailTest, E15){
+TEST(TestCornerCases, E15){
 #define GEN_COMPARATOR(op)                                       \
   {                                                              \
     auto a = F();                                                \
@@ -195,7 +195,7 @@ TEST(FailTest, E15){
 
 }
 
-TEST(FailTest, E16){
+TEST(TestCornerCases, E16){
 #define GEN_BOOLS(op)                                                         \
   {                                                                           \
     auto a = F();                                                             \
@@ -213,21 +213,21 @@ TEST(FailTest, E16){
 
     GEN_BOOLS(||) GEN_BOOLS(&&)}
 
-TEST(FailTest, E17) {
+TEST(TestCornerCases, E17) {
   auto r = F(1);
   Succeed(
       "def f(float(1) a) -> (b) { b(i) = 4.0 where a(i) exists }", {F(1)}, {r});
   CHECK_EQ(at::Scalar(r[0]).toFloat(), 4);
 }
 
-TEST(FailTest, E18) {
+TEST(TestCornerCases, E18) {
   auto a = F(1);
   auto r = F(1);
   Succeed(
       "def f(float(1) a) -> (b) { b(i) = 2*foo where foo = a(i) }", {a}, {r});
   CHECK_EQ(at::Scalar(r[0]).toFloat(), at::Scalar(a[0]).toFloat() * 2);
 }
-TEST(FailTest, E19) {
+TEST(TestCornerCases, E19) {
   Fail(
       "undefined variable",
       "def f(float(1) a) -> (b) { b(i) = 2*foo where foo = a(i), foo in 1:2 }",