# `Edifice.Convolutional.Conv`
[🔗](https://github.com/blasphemetheus/edifice/blob/main/lib/edifice/convolutional/conv.ex#L1)

Conv1D and Conv2D building blocks for convolutional neural networks.

Provides composable convolutional blocks and full model builders for both
1D (sequence) and 2D (image) processing. Each block follows the pattern:
convolution -> batch normalization -> activation -> dropout.

## Architecture (Conv1D)

```
Input [batch, seq_len, channels]
      |
      v
+---------------------------+
| Conv1D -> BN -> Act -> Drop|  Block 1
+---------------------------+
      |
      v
+---------------------------+
| Conv1D -> BN -> Act -> Drop|  Block 2
+---------------------------+
      |        (optional pooling)
      v
Output [batch, seq_len', channels']
```

## Usage

    # Build a 1D convolutional model for sequence processing
    model = Conv.build_conv1d(
      input_size: 64,
      channels: [128, 256, 512],
      kernel_sizes: [3, 3, 3],
      activation: :relu,
      dropout: 0.1,
      pooling: :max
    )

    # Build a 2D convolutional model for image processing
    model = Conv.build_conv2d(
      input_shape: {nil, 32, 32, 3},
      channels: [32, 64, 128],
      kernel_sizes: [3, 3, 3],
      activation: :relu,
      dropout: 0.1,
      pooling: :max
    )

    # Use individual blocks as building blocks
    input = Axon.input("input", shape: {nil, 100, 64})
    block = Conv.conv1d_block(input, 128, kernel_size: 3, activation: :gelu)

# `build_opt`

```elixir
@type build_opt() ::
  {:input_size, pos_integer()}
  | {:channels, [pos_integer()]}
  | {:kernel_sizes, pos_integer() | [pos_integer()]}
  | {:activation, atom()}
  | {:dropout, float()}
  | {:pooling, atom() | nil}
  | {:seq_len, pos_integer() | nil}
```

Options for `build/1`.

# `build`

```elixir
@spec build([build_opt()]) :: Axon.t()
```

Alias for `build_conv1d/1`.

# `build_conv1d`

```elixir
@spec build_conv1d(keyword()) :: Axon.t()
```

Build a 1D convolutional model for sequence processing.

## Options

  - `:input_size` - Number of input channels/features (required)
  - `:channels` - List of output channel counts per layer (default: [64, 128, 256])
  - `:kernel_sizes` - List of kernel sizes per layer, or single integer for all layers (default: 3)
  - `:activation` - Activation function atom (default: :relu)
  - `:dropout` - Dropout rate (default: 0.1)
  - `:pooling` - Pooling type: `:max`, `:avg`, or `nil` for no pooling (default: nil)
  - `:seq_len` - Expected sequence length, or nil for dynamic (default: nil)

## Returns

  An Axon model taking `[batch, seq_len, input_size]` and outputting
  `[batch, seq_len', last_channel_count]`.

# `build_conv2d`

```elixir
@spec build_conv2d(keyword()) :: Axon.t()
```

Build a 2D convolutional model for image processing.

## Options

  - `:input_shape` - Input shape as `{nil, height, width, channels}` (required)
  - `:channels` - List of output channel counts per layer (default: [32, 64, 128])
  - `:kernel_sizes` - List of kernel sizes per layer, or single integer for all layers (default: 3)
  - `:activation` - Activation function atom (default: :relu)
  - `:dropout` - Dropout rate (default: 0.1)
  - `:pooling` - Pooling type: `:max`, `:avg`, or `nil` for no pooling (default: nil)

## Returns

  An Axon model taking `[batch, height, width, channels]` (NHWC) and outputting
  `[batch, height', width', last_channel_count]`.

# `conv1d_block`

```elixir
@spec conv1d_block(Axon.t(), pos_integer(), keyword()) :: Axon.t()
```

Build a single conv1d -> batch_norm -> activation -> dropout block.

## Parameters

  - `input` - Input Axon node with shape `[batch, seq_len, channels]`
  - `out_channels` - Number of output channels

## Options

  - `:kernel_size` - Convolution kernel size (default: 3)
  - `:activation` - Activation function atom (default: :relu)
  - `:dropout` - Dropout rate, 0.0 to skip (default: 0.1)
  - `:name` - Layer name prefix (default: "conv1d_block")
  - `:padding` - Padding mode: `:same` or `:valid` (default: :same)
  - `:strides` - Convolution stride (default: 1)

## Returns

  An Axon node with shape `[batch, seq_len', out_channels]`.

# `conv2d_block`

```elixir
@spec conv2d_block(Axon.t(), pos_integer(), keyword()) :: Axon.t()
```

Build a single conv2d -> batch_norm -> activation -> dropout block.

## Parameters

  - `input` - Input Axon node with shape `[batch, height, width, channels]`
  - `out_channels` - Number of output channels

## Options

  - `:kernel_size` - Convolution kernel size (default: 3)
  - `:activation` - Activation function atom (default: :relu)
  - `:dropout` - Dropout rate, 0.0 to skip (default: 0.1)
  - `:name` - Layer name prefix (default: "conv2d_block")
  - `:padding` - Padding mode: `:same` or `:valid` (default: :same)
  - `:strides` - Convolution stride (default: 1)

## Returns

  An Axon node with shape `[batch, height', width', out_channels]`.

# `output_size`

```elixir
@spec output_size(keyword()) :: pos_integer()
```

Get the output channel count for a convolutional model with the given options.

---

*Consult [api-reference.md](api-reference.md) for complete listing*