How do I use fbcunn nn.HSM - neural-network

Question

I'd love a simple example of how to use the nn.HSM hierarchical softmax module in fbcunn.
The documentation is nonexistent (see here). I did find this user group post which describes what the cluster "mapping" should look like, and there are some tests lying around for the module and its corresponding criterion but none of them use the module in a "normal" way, e.g. as the final layer in a simple feed-forward neural network.

Answer 1

Here's a small example that should work:
require 'torch'
require 'fbcunn'
hidden_dim = 10
input_dim = 20
batch_size = 1
gpuid = 0
function to_cuda(x) return gpuid >= 0 and x:cuda() or x end
inputs = to_cuda(torch.rand(batch_size, input_dim))
targets = to_cuda(torch.ones(batch_size):long())
-- #mapping should equal the number of possible outputs, in our case 8
-- this mapping defines 4 clusters, two size 2, one size 3, one size 1
mapping = { {1, 1}, {1, 2}, {2, 1}, {2, 2}, {2, 3}, {3, 1}, {4, 1}, {4, 2} }
linear = to_cuda(nn.Sequential():add(nn.Linear(input_dim,hidden_dim)))
hsm = to_cuda(nn.HSM(mapping, hidden_dim))
h_out = linear:forward(inputs)
s_out, err = hsm:forward(h_out, targets)
df_ds = hsm:backward(h_out, targets)
linear:backward(inputs, df_ds)
Note that as of this posting, the above example will only work on a GPU (cannot run on CPU, aka gpuid=-1); See this issue.
Additionally, the GPU must have compute capability 3.5 or greater; the example at the link above provides an even smaller example that will run on a GPU with compute capability 3.0.