API design principles

User API

• Underlying maths and probability libraries should not be exposed, i.e. TensorFlow
• Interaction with GEM API is via Numpy data structures, strings, or Python constants
• High-level API is object-orientated e.g.

gem_model = """
x: Vector()
alpha ~ Normal(0, 1)
beta ~ Normal(0, 1)

y ~ Normal(alpha + beta*x, 0.1)
"""

model = GEM(gem_model, const_data={'x': np.random.uniform(size=10), 
                                   'y': np.random.uniform(size=10)})

mcmc = gem.mcmc.MCMC(model)
mcmc.add_step(["alpha"], algorithm="HMC", step_size=0.1, num_leapfrog_steps=20)
mcmc.add_step(["beta"], algorithm="Metropolis", adaptive=True, initial_scaling_constant=0.44)

samples, results = mcmc.sample(num_samples=1000, 
                               start={'alpha': 1.0, 'beta': 0.0}, 
                               burnin=300, 
                               chain=4,
                               num_steps_between_samples=9)

What should version 1.0.0 be capable of?

• Linear discrete-time meta-population epidemic model (chain binomial/multinomial)
• Hierarchical parameters
• Implement Metropolis-Hastings-based inference -- data-augmentation MCMC
• Forward simulation, with ability to condition on parameter values
• Ability to fit UK COVID-19 Lancaster model.

What should version 1.0.0 not be capable of?

• Continuous time
• Automatic MCMC algorithm construction. User specifics update steps.
• No facility for adding user-specified functions in gemlang
• Branching state transition models
• Cyclic state transition models