#!/usr/bin/env python
# coding: utf-8

# # Deriving evolver and driver classes
# 
# In `micromagneticmodel` package, base classes `micromagneticmodel.Driver` and `micromagneticmodel.Evolver` are defined. Their purpose is to build individual evolvers and drivers in a particular micromagnetic calculator. In this tutorial, we will demonstrate some of their basic properties, on an example of a `micromagneticmodel.Driver` class. The behaviour of the `micromagneticmodel.Evolver` class is the same.
# 
# Let us derive `MyDriver` class. In order to define it, `_allowed_attributes` list must be defined. It is a list of strings, which lists the kwargs which are allowed to be passed. Additionally, the driver must define a property `_x` for the independent variable (e.g. time).

# In[1]:


import micromagneticmodel as mm


class MyDriver(mm.Driver):
    _allowed_attributes = ["arg1", "arg2"]

    @property
    def _x(self):
        return "t"

    def drive(system):
        return system


# `Driver` class does not require any parameters to be passed at initialisation. If a keyword argument is from `_allowed_kwargs` list, it will be assigned as a class attribute. Otherwise, `AttributeError` will be raised.

# In[2]:


driver = MyDriver(arg1=1, arg2="value")


# The attributes are

# In[3]:


driver.arg1


# In[4]:


driver.arg2


# If we try to pass a keyword argument at initialisation, which is not in the `_allowed_kwargs` list, `AttributeError` is rased:

# In[5]:


try:
    driver = MyDriver(arg3=1)
except AttributeError:
    print("Exception raised.")


# The main driver method which must be implemented by a derived class is `drive`.

# In[6]:


try:
    driver.drive()
except NotImplementedError:
    print("Exception raised.")


# To build a driver for an existing external package class `micromagneticmodel.ExternalDriver` should be used. This class provides an additional method `schedule` to submit a calculation job to a scheduling system.
# 
# Furthermore, it has a generic implementation for `drive` and `schedule` that consists of the following steps:
# - Create a directory to save the input and output in.
# - Write the input files for the existing simulation package.
# - Call the existing simulation package to run the simulation. / Schedule a job to run the simulation.
# - Update the `system` object with the simulation results (`drive` only).
# 
# Simulation-package specific things such as writing input files and reading results must be implemented in a number of pre-defined abstract methods inside the derived class. Refer to the API reference for more details.