Base.Cartesian

(エクスポートされていない)Cartesian モジュールには、多次元アルゴリズムの記述を容易にするマクロが用意されています。多くの場合、このようなアルゴリズムは straightforward techniques を使って記述できますが、Base.Cartesian が依然として役立つ、あるいは必要となるケースもいくつかあります。

Principles of usage

使用例を簡単に示します。

@nloops 3 i A begin
    s += @nref 3 A i
end

これは次のコードを生成します。

for i_3 = axes(A, 3)
    for i_2 = axes(A, 2)
        for i_1 = axes(A, 1)
            s += A[i_1, i_2, i_3]
        end
    end
end

一般に、Cartesian を使うと、この例の入れ子になったループのように、繰り返し要素を含む汎用コードを記述できます。ほかにも、式の繰り返し(ループ展開など)や、「スプラット」構文(i...)を使わずに可変個の引数を取る関数呼び出しを作成するといった用途があります。

Basic syntax

@nloops の基本的な構文は次のとおりです。

  • 第1引数には、ループ数を指定する整数(変数ではありません)を指定します。
  • 第2引数には、イテレーター変数に付けるシンボルの接頭辞を指定します。ここでは i を使い、i_1, i_2, i_3 という変数が生成されます。
  • 第3引数には、各イテレーター変数の範囲を指定します。ここに変数(シンボル)を指定すると、axes(A, dim) として扱われます。より柔軟な方法として、後述する無名関数式の構文も使えます。
  • 最後の引数には、ループ本体を指定します。ここでは、begin...end の間に記述されている部分が該当します。

@nloops には、reference section で説明する追加機能もあります。

@nref も同様のパターンに従い、@nref 3 A i から A[i_1,i_2,i_3] を生成します。基本的には左から右へ読みます。そのため、@nloops は @nloops 3 i A expr です(for i_2 = axes(A, 2) では、i_2 が左側にあり、範囲が右側にあります)。一方、@nref は @nref 3 A i です(A[i_1,i_2,i_3] では、配列が先に来るためです)。

Cartesian を使ってコードを開発している場合、生成されたコードを @macroexpand で確認すると、デバッグが容易になることがあります。

julia> @macroexpand @nref 2 A i
:(A[i_1, i_2])

Supplying the number of expressions

これら2つのマクロの第1引数には、式の数を指定します。これは整数でなければなりません。複数の次元で動作する関数を作成する場合、この値をハードコードしたくないこともあるでしょう。推奨される方法は、@generated function を使うことです。例を示します。

@generated function mysum(A::Array{T,N}) where {T,N}
    quote
        s = zero(T)
        @nloops $N i A begin
            s += @nref $N A i
        end
        s
    end
end

もちろん、quote ブロックの前に、式を用意したり計算を行ったりすることもできます。

Anonymous-function expressions as macro arguments

Cartesian の最も強力な機能のひとつは、パース時に評価される無名関数式を指定できることです。簡単な例を見てみましょう。

@nexprs 2 j->(i_j = 1)

@nexprs は、一定のパターンに従う n 式を生成します。このコードは、次の文を生成します。

i_1 = 1
i_2 = 1

生成される各文では、「独立した」j(無名関数の変数)が、範囲 1:2 内の値に置き換えられます。一般に、Cartesian では LaTeX に似た構文を使います。これにより、インデックス j に対する計算が可能になります。配列のストライドを計算する例を示します。

s_1 = 1
@nexprs 3 j->(s_{j+1} = s_j * size(A, j))

これにより、次の式が生成されます。

s_1 = 1
s_2 = s_1 * size(A, 1)
s_3 = s_2 * size(A, 2)
s_4 = s_3 * size(A, 3)

無名関数式は、実際にさまざまな用途で使えます。

Macro reference

Base.Cartesian.@nloops — Macro
@nloops N itersym rangeexpr bodyexpr
@nloops N itersym rangeexpr preexpr bodyexpr
@nloops N itersym rangeexpr preexpr postexpr bodyexpr

N の入れ子ループを生成します。反復変数の接頭辞には itersym を使用します。rangeexpr には無名関数式を指定できます。または、単純なシンボル var を指定することもでき、その場合、次元 d の範囲は axes(var, d) になります。

必要に応じて、「pre」と「post」の式を指定できます。これらはそれぞれ、各ループ本体の最初と最後に実行されます。たとえば、次のように指定すると、

@nloops 2 i A d -> j_d = min(i_d, 5) begin
    s += @nref 2 A j
end

次のコードが生成されます。

for i_2 = axes(A, 2)
    j_2 = min(i_2, 5)
    for i_1 = axes(A, 1)
        j_1 = min(i_1, 5)
        s += A[j_1, j_2]
    end
end

post 式だけを指定する場合は、pre 式に nothing を指定してください。括弧とセミコロンを使うと、複数の文からなる式を指定できます。

source
Base.Cartesian.@nref — Macro
@nref N A indexexpr

A[i_1, i_2, ...]のような式を生成します。indexexprには、反復記号の接頭辞または無名関数式を指定できます。

Examples

julia> @macroexpand Base.Cartesian.@nref 3 A i
:(A[i_1, i_2, i_3])
source
Base.Cartesian.@nextract — Macro
@nextract N esym isym

isymから値を取り出すための変数N、esym_1、esym_2、...、esym_Nを生成します。isymには、Symbolまたは無名関数式を指定できます。

@nextract 2 x yでは次のように生成されます。

x_1 = y[1]
x_2 = y[2]

一方、@nextract 3 x d->y[2d-1]では次のようになります。

x_1 = y[1]
x_2 = y[3]
x_3 = y[5]
source
Base.Cartesian.@nexprs — Macro
@nexprs N expr

N 式を生成します。expr は無名関数式にしてください。

Examples

julia> @macroexpand Base.Cartesian.@nexprs 4 i -> y[i] = A[i+j]
quote
    y[1] = A[1 + j]
    y[2] = A[2 + j]
    y[3] = A[3 + j]
    y[4] = A[4 + j]
end
source
Base.Cartesian.@ncall — Macro
@ncall N f sym...

関数呼び出し式を生成します。sym は任意の数の関数引数を表し、最後の引数には無名関数式を指定できます。この式は N 個の引数に展開されます。

たとえば、@ncall 3 func a は次を生成します。

func(a_1, a_2, a_3)

一方、@ncall 2 func a b i->c[i] は次のようになります。

func(a, b, c[1], c[2])
source
Base.Cartesian.@ncallkw — Macro
@ncallkw N f kw sym...

キーワード引数を含む関数呼び出し式を生成します kw...。@ncallの場合と同様に、symは任意の数の関数引数を表し、最後の引数は無名関数式でもかまいません。これはN個の引数に展開されます。

Examples

julia> using Base.Cartesian

julia> f(x...; a, b = 1, c = 2, d = 3) = +(x..., a, b, c, d);

julia> x_1, x_2 = (-1, -2); b = 0; kw = (c = 0, d = 0);

julia> @ncallkw 2 f (; a = 0, b, kw...) x
-3
source
Base.Cartesian.@ntuple — Macro
@ntuple N expr

Nタプルを生成します。@ntuple 2 iは(i_1, i_2)を生成し、@ntuple 2 k->k+1は(2,3)を生成します。

source
Base.Cartesian.@nall — Macro
@nall N expr

無名関数式 expr によって生成されるすべての式が true と評価されるかどうかを確認します。

@nall 3 d->(i_d > 1) は式 (i_1 > 1 && i_2 > 1 && i_3 > 1) を生成します。これは境界チェックに便利です。

source
Base.Cartesian.@nany — Macro
@nany N expr

無名関数式 expr が生成する式の中に、true と評価されるものがあるかどうかを確認します。

@nany 3 d->(i_d > 1) は、式 (i_1 > 1 || i_2 > 1 || i_3 > 1) を生成します。

source
Base.Cartesian.@nif — Macro
@nif N conditionexpr expr
@nif N conditionexpr expr elseexpr

一連の if ... elseif ... else ... end 文を生成します。たとえば、

@nif 3 d->(i_d >= size(A,d)) d->(error("Dimension ", d, " too big")) d->println("All OK")

は、次のように生成します。

if i_1 > size(A, 1)
    error("Dimension ", 1, " too big")
elseif i_2 > size(A, 2)
    error("Dimension ", 2, " too big")
else
    println("All OK")
end
source