Python Compilation API#

cutile_basic#

BASIC to CUDA Tile IR compiler.

cutile_basic.compile_basic_to_cubin( source: str, *, gpu_arch: str | None = None, array_size: int | None = None, num_ctas: int | None = None, ) → CompilationResult[source]#

Compile BASIC source to a .cubin via the bytecode backend.

Parameters:

source – BASIC source code.
gpu_arch – Target GPU architecture (e.g. "sm_120"). None auto-detects from the current device.
array_size – Total elements per array; None infers from DIM.
num_ctas – CTAs-per-CGA optimisation hint; None disables.

Returns:

A CompilationResult with cubin_path and kernel meta.

class cutile_basic.CompilationResult(cubin_path: str, meta: dict)[source]#: Result of compiling BASIC source to a .cubin file.

cutile_basic.detect_gpu_arch() → str[source]#: Return the GPU architecture string (e.g. ‘sm_120’) for device 0.

cutile_basic.bytecode#

Bytecode backend: AST → cuTile bytecode.

exception cutile_basic.bytecode.BytecodeBackendError[source]#

class cutile_basic.bytecode.BytecodeBackend( analyzed: AnalyzedProgram, gpu_arch: str = 'sm_120', array_size: int | None = None, num_ctas: int | None = None, )[source]#

Compile an AnalyzedProgram directly to cuTile bytecode.

generate(array_size: int | None = None) → bytes[source]#: Generate cuTile bytecode from the analyzed program.

compile_to_cubin( output_dir: str | None = None, array_size: int | None = None, ) → str[source]#: Generate bytecode, run tileiras, return path to .cubin.

class cutile_basic.bytecode.CompilationResult(cubin_path: str, meta: dict)[source]#: Result of compiling BASIC source to a .cubin file.

cutile_basic.bytecode.compile_basic_to_cubin( source: str, *, gpu_arch: str | None = None, array_size: int | None = None, num_ctas: int | None = None, ) → CompilationResult[source]#

Compile BASIC source to a .cubin via the bytecode backend.

Parameters:

source – BASIC source code.
gpu_arch – Target GPU architecture (e.g. "sm_120"). None auto-detects from the current device.
array_size – Total elements per array; None infers from DIM.
num_ctas – CTAs-per-CGA optimisation hint; None disables.

Returns:

A CompilationResult with cubin_path and kernel meta.

cutile_basic.gpu#

GPU utilities (architecture detection, etc.).

cutile_basic.gpu.detect_gpu_arch() → str[source]#: Return the GPU architecture string (e.g. ‘sm_120’) for device 0.

cutile_basic.cli#

CLI entry point for the BASIC to CUDA Tile IR compiler.

cutile_basic.cli.main()[source]#

Internals#

These modules implement the compiler pipeline stages. They are used by the public API and CLI but can also be imported directly.

cutile_basic.tokens#

Token types and Token dataclass for the BASIC lexer.

class cutile_basic.tokens.TokenType(*values)[source]#

INTEGER = 1#

FLOAT = 2#

STRING = 3#

IDENTIFIER = 4#

LET = 5#

PRINT = 6#

INPUT = 7#

IF = 8#

THEN = 9#

ELSE = 10#

ENDIF = 11#

FOR = 12#

TO = 13#

STEP = 14#

NEXT = 15#

WHILE = 16#

WEND = 17#

GOTO = 18#

GOSUB = 19#

RETURN = 20#

DIM = 21#

REM = 22#

DATA = 23#

READ = 24#

END = 25#

STOP = 26#

AND = 27#

OR = 28#

NOT = 29#

MOD = 30#

OUTPUT = 31#

TILE = 32#

BID = 33#

PLUS = 34#

MINUS = 35#

STAR = 36#

SLASH = 37#

CARET = 38#

EQ = 39#

NEQ = 40#

LT = 41#

GT = 42#

LE = 43#

GE = 44#

LPAREN = 45#

RPAREN = 46#

COMMA = 47#

SEMICOLON = 48#

NEWLINE = 49#

EOF = 50#

COLON = 51#

class cutile_basic.tokens.Token( type: cutile_basic.tokens.TokenType, value: str, line: int, col: int, )[source]#

type: TokenType#

value: str#

line: int#

col: int#

cutile_basic.lexer#

Lexer for BASIC source code.

exception cutile_basic.lexer.LexError(msg: str, line: int, col: int)[source]#

cutile_basic.lexer.lex(source: str) → list[Token][source]#: Tokenize BASIC source code into a list of tokens.

cutile_basic.ast_nodes#

AST node classes for the BASIC parser.

class cutile_basic.ast_nodes.NumberLiteral(value: 'float | int', line: 'int' = 0)[source]#

value: float | int#

line: int = 0#

class cutile_basic.ast_nodes.StringLiteral(value: 'str', line: 'int' = 0)[source]#

value: str#

line: int = 0#

class cutile_basic.ast_nodes.Variable(name: 'str', line: 'int' = 0)[source]#

name: str#

line: int = 0#

class cutile_basic.ast_nodes.ArrayAccess( name: 'str', index: 'Expression', index2: 'Expression | None' = None, line: 'int' = 0, )[source]#

name: str#

index: NumberLiteral | StringLiteral | Variable | ArrayAccess | UnaryOp | BinaryOp | FunctionCall#

index2: NumberLiteral | StringLiteral | Variable | ArrayAccess | UnaryOp | BinaryOp | FunctionCall | None = None#

line: int = 0#

class cutile_basic.ast_nodes.UnaryOp(op: 'str', operand: 'Expression', line: 'int' = 0)[source]#

op: str#

operand: NumberLiteral | StringLiteral | Variable | ArrayAccess | UnaryOp | BinaryOp | FunctionCall#

line: int = 0#

class cutile_basic.ast_nodes.BinaryOp( op: 'str', left: 'Expression', right: 'Expression', line: 'int' = 0, )[source]#

op: str#

left: NumberLiteral | StringLiteral | Variable | ArrayAccess | UnaryOp | BinaryOp | FunctionCall#

right: NumberLiteral | StringLiteral | Variable | ArrayAccess | UnaryOp | BinaryOp | FunctionCall#

line: int = 0#

class cutile_basic.ast_nodes.FunctionCall(name: 'str', args: 'list[Expression]', line: 'int' = 0)[source]#

name: str#

args: list[NumberLiteral | StringLiteral | Variable | ArrayAccess | UnaryOp | BinaryOp | FunctionCall]#

line: int = 0#

class cutile_basic.ast_nodes.LetStatement( target: 'Variable | ArrayAccess', value: 'Expression', line: 'int' = 0, )[source]#

target: Variable | ArrayAccess#

value: NumberLiteral | StringLiteral | Variable | ArrayAccess | UnaryOp | BinaryOp | FunctionCall#

line: int = 0#

class cutile_basic.ast_nodes.PrintStatement( items: 'list[Expression]', newline: 'bool' = True, line: 'int' = 0, )[source]#

items: list[NumberLiteral | StringLiteral | Variable | ArrayAccess | UnaryOp | BinaryOp | FunctionCall]#

newline: bool = True#

line: int = 0#

class cutile_basic.ast_nodes.InputStatement( prompt: 'Optional[str]', variables: 'list[Variable]', is_array: 'list[bool]' = <factory>, line: 'int' = 0, )[source]#

prompt: str | None#

variables: list[Variable]#

is_array: list[bool]#

line: int = 0#

class cutile_basic.ast_nodes.IfStatement( condition: 'Expression', then_body: 'list[Statement]', else_body: 'list[Statement]', line: 'int' = 0, )[source]#

condition: NumberLiteral | StringLiteral | Variable | ArrayAccess | UnaryOp | BinaryOp | FunctionCall#

then_body: list[LetStatement | PrintStatement | InputStatement | IfStatement | ForStatement | WhileStatement | GotoStatement | GosubStatement | ReturnStatement | DimStatement | RemStatement | DataStatement | ReadStatement | EndStatement | StopStatement | TileStatement | OutputStatement]#

else_body: list[LetStatement | PrintStatement | InputStatement | IfStatement | ForStatement | WhileStatement | GotoStatement | GosubStatement | ReturnStatement | DimStatement | RemStatement | DataStatement | ReadStatement | EndStatement | StopStatement | TileStatement | OutputStatement]#

line: int = 0#

class cutile_basic.ast_nodes.ForStatement( var: 'Variable', start: 'Expression', end: 'Expression', step: 'Optional[Expression]', body: 'list[Statement]', line: 'int' = 0, )[source]#

var: Variable#

start: NumberLiteral | StringLiteral | Variable | ArrayAccess | UnaryOp | BinaryOp | FunctionCall#

end: NumberLiteral | StringLiteral | Variable | ArrayAccess | UnaryOp | BinaryOp | FunctionCall#

step: NumberLiteral | StringLiteral | Variable | ArrayAccess | UnaryOp | BinaryOp | FunctionCall | None#

body: list[LetStatement | PrintStatement | InputStatement | IfStatement | ForStatement | WhileStatement | GotoStatement | GosubStatement | ReturnStatement | DimStatement | RemStatement | DataStatement | ReadStatement | EndStatement | StopStatement | TileStatement | OutputStatement]#

line: int = 0#

class cutile_basic.ast_nodes.WhileStatement( condition: 'Expression', body: 'list[Statement]', line: 'int' = 0, )[source]#

condition: NumberLiteral | StringLiteral | Variable | ArrayAccess | UnaryOp | BinaryOp | FunctionCall#

body: list[LetStatement | PrintStatement | InputStatement | IfStatement | ForStatement | WhileStatement | GotoStatement | GosubStatement | ReturnStatement | DimStatement | RemStatement | DataStatement | ReadStatement | EndStatement | StopStatement | TileStatement | OutputStatement]#

line: int = 0#

class cutile_basic.ast_nodes.GotoStatement(target: 'int', line: 'int' = 0)[source]#

target: int#

line: int = 0#

class cutile_basic.ast_nodes.GosubStatement(target: 'int', line: 'int' = 0)[source]#

target: int#

line: int = 0#

class cutile_basic.ast_nodes.ReturnStatement(line: 'int' = 0)[source]#

line: int = 0#

class cutile_basic.ast_nodes.DimStatement(name: 'str', sizes: 'list[Expression]', line: 'int' = 0)[source]#

name: str#

sizes: list[NumberLiteral | StringLiteral | Variable | ArrayAccess | UnaryOp | BinaryOp | FunctionCall]#

line: int = 0#

class cutile_basic.ast_nodes.RemStatement(comment: 'str', line: 'int' = 0)[source]#

comment: str#

line: int = 0#

class cutile_basic.ast_nodes.DataStatement(values: 'list[float | int | str]', line: 'int' = 0)[source]#

values: list[float | int | str]#

line: int = 0#

class cutile_basic.ast_nodes.ReadStatement(variables: 'list[Variable]', line: 'int' = 0)[source]#

variables: list[Variable]#

line: int = 0#

class cutile_basic.ast_nodes.EndStatement(line: 'int' = 0)[source]#

line: int = 0#

class cutile_basic.ast_nodes.StopStatement(line: 'int' = 0)[source]#

line: int = 0#

class cutile_basic.ast_nodes.TileStatement(name: 'str', sizes: 'list[Expression]', line: 'int' = 0)[source]#

name: str#

sizes: list[NumberLiteral | StringLiteral | Variable | ArrayAccess | UnaryOp | BinaryOp | FunctionCall]#

line: int = 0#

class cutile_basic.ast_nodes.OutputStatement(variables: 'list[Variable]', line: 'int' = 0)[source]#

variables: list[Variable]#

line: int = 0#

class cutile_basic.ast_nodes.Program( statements: 'list[Statement]', line_map: 'dict[int, int]'=<factory>, )[source]#

statements: list[LetStatement | PrintStatement | InputStatement | IfStatement | ForStatement | WhileStatement | GotoStatement | GosubStatement | ReturnStatement | DimStatement | RemStatement | DataStatement | ReadStatement | EndStatement | StopStatement | TileStatement | OutputStatement]#

line_map: dict[int, int]#

cutile_basic.parser#

Recursive descent parser for BASIC.

exception cutile_basic.parser.ParseError(msg: str, token: Token)[source]#

class cutile_basic.parser.Parser(tokens: list[Token])[source]#

peek() → Token[source]#

advance() → Token[source]#

expect( tt: TokenType, ) → Token[source]#

at(*types: TokenType) → bool[source]#

match( *types: TokenType, ) → Token | None[source]#

skip_newlines()[source]#

parse() → Program[source]#

parse_statement() → LetStatement | PrintStatement | InputStatement | IfStatement | ForStatement | WhileStatement | GotoStatement | GosubStatement | ReturnStatement | DimStatement | RemStatement | DataStatement | ReadStatement | EndStatement | StopStatement | TileStatement | OutputStatement[source]#

parse_let() → LetStatement[source]#

parse_implicit_let() → LetStatement[source]#

parse_lvalue() → Variable | ArrayAccess[source]#

parse_print() → PrintStatement[source]#

parse_input() → InputStatement[source]#

parse_if() → IfStatement[source]#

parse_for() → ForStatement[source]#

parse_while() → WhileStatement[source]#

parse_goto() → GotoStatement[source]#

parse_gosub() → GosubStatement[source]#

parse_dim() → DimStatement | list[DimStatement][source]#

parse_data() → DataStatement[source]#

parse_output() → OutputStatement[source]#

parse_tile() → TileStatement | list[TileStatement][source]#

parse_read() → ReadStatement[source]#

parse_expression() → NumberLiteral | StringLiteral | Variable | ArrayAccess | UnaryOp | BinaryOp | FunctionCall[source]#

parse_or() → NumberLiteral | StringLiteral | Variable | ArrayAccess | UnaryOp | BinaryOp | FunctionCall[source]#

parse_and() → NumberLiteral | StringLiteral | Variable | ArrayAccess | UnaryOp | BinaryOp | FunctionCall[source]#

parse_not() → NumberLiteral | StringLiteral | Variable | ArrayAccess | UnaryOp | BinaryOp | FunctionCall[source]#

parse_comparison() → NumberLiteral | StringLiteral | Variable | ArrayAccess | UnaryOp | BinaryOp | FunctionCall[source]#

parse_addition() → NumberLiteral | StringLiteral | Variable | ArrayAccess | UnaryOp | BinaryOp | FunctionCall[source]#

parse_multiplication() → NumberLiteral | StringLiteral | Variable | ArrayAccess | UnaryOp | BinaryOp | FunctionCall[source]#

parse_power() → NumberLiteral | StringLiteral | Variable | ArrayAccess | UnaryOp | BinaryOp | FunctionCall[source]#

parse_unary() → NumberLiteral | StringLiteral | Variable | ArrayAccess | UnaryOp | BinaryOp | FunctionCall[source]#

parse_primary() → NumberLiteral | StringLiteral | Variable | ArrayAccess | UnaryOp | BinaryOp | FunctionCall[source]#

cutile_basic.parser.parse( tokens: list[Token], ) → Program[source]#: Parse a list of tokens into an AST.

cutile_basic.analyzer#

Semantic analyzer: type inference, INPUT/OUTPUT tracking, DATA/READ collection.

exception cutile_basic.analyzer.AnalyzeError[source]#

class cutile_basic.analyzer.BasicType(*values)[source]#

F32 = 1#

I32 = 2#

I1 = 3#

STRING = 4#

tile_type() → str[source]#

scalar_type() → str[source]#

class cutile_basic.analyzer.SymbolInfo( name: 'str', type: 'BasicType', is_array: 'bool' = False, array_size: 'int | None' = None, tile_shape: 'list[int] | None' = None, )[source]#

name: str#

type: BasicType#

is_array: bool = False#

array_size: int | None = None#

tile_shape: list[int] | None = None#

class cutile_basic.analyzer.AnalyzedProgram( statements: 'list[ast.Statement]', symbols: 'dict[str, SymbolInfo]', data_values: 'list[float | int]', input_vars: 'list[str]', output_vars: 'list[str]' = None, has_goto: 'bool' = False, )[source]#

statements: list[LetStatement | PrintStatement | InputStatement | IfStatement | ForStatement | WhileStatement | GotoStatement | GosubStatement | ReturnStatement | DimStatement | RemStatement | DataStatement | ReadStatement | EndStatement | StopStatement | TileStatement | OutputStatement]#

symbols: dict[str, SymbolInfo]#

data_values: list[float | int]#

input_vars: list[str]#

output_vars: list[str] = None#

has_goto: bool = False#

class cutile_basic.analyzer.Analyzer[source]#

symbols: dict[str, SymbolInfo]#

data_values: list[float | int]#

input_vars: list[str]#

output_vars: list[str]#

goto_targets: set[int]#

analyze( program: Program, ) → AnalyzedProgram[source]#

cutile_basic.analyzer.analyze( program: Program, ) → AnalyzedProgram[source]#: Analyze a parsed BASIC program.