modelverse/doc/wrappers.rst

Wrappers
========

Several wrappers can be defined for the Modelverse, as the Modelverse is merely a service running externally.
To communicate effectively, and automatically, a programming language wrapper is recommended.
Nonetheless, it is possible to communicatie manually as well.
These are some of the implemented wrappers.

Prompt
------

The simplest wrapper is the prompt wrapper, which merely sends the input and output directly to the user.
This wrapper has almost no code, but requires users to manually decide which content to send next.
It has no built-in integration with any model or action language compilers.
Nonetheless, it is an easy way to test out the raw communication protocol manually.

Python
------

The first real wrapper is the Python-based wrapper.
It provides a set of functions for use by Python code.
These functions wrap not only the interface, but also provides simple error handling through the use of Python exceptions and contains the model and action language compilers.
An overview of all functions and associatied exceptions is provided below.
All operations happen *synchronously*, meaning that they block until the Modelverse has performed the requested operation.

Note that some functions are only applicable in a certain *context*.
In practice, this means that you should first issue the *init* and *login* operations, as otherwise your connection with the Modelverse will not have started up yet.

For each function, we provide an example to indicate how this operation can be used.
In these first examples, assume that all referenced elements are present, all permissions are granted, etc.
For each exception, then, we provide an example where it can occur.
In these examples, the problem is often caused by an non-existing element or unsatisfied permissions.
From the example, it should be clear what the problem is.

Functions
^^^^^^^^^

.. function:: init(address_param="http://127.0.0.1:8001", timeout=20.0)

   Start up the connection to the Modelverse, residing at *address_param*.
   This connection is an XML/HTTPRequest and will start up a new task at the Modelverse.
   Retries for *timeout* seconds until giving up.
   The timeout includes all HTTP errors, and will therefore keep retrying even on failed attempts.
   As this request is synchronous, like all others, it will block until a connection has been established.

   Examples:

   To create a connection to the Modelverse that runs locally at port 8001 (default configuration):
   .. code::
      >> init()

   To create a connection to the Modelverse running remotely:
   .. code::
      >> init("http://modelverse.uantwerpen.be:8001")

.. function:: login(username, password)

   Explanation
   Logs in the currently active Modelverse connection to the specified *username* and *password*.
   If the user does not exist, it will create a new user with the specified password.
   If the user already exists, it will try to log in with the provided password.

   Examples:

   To login as user user1, with the specified password:
   .. code::
      >> login("user1", "my_password")

.. function:: model_add(model_name, metamodel_name, model_code=None)

   Explanation
   Upload a new model that can later be referred to as *model_name*, conforming to *metamodel_name*.
   The model itself is stored in the string *model_code*.
   This string is parsed using the HUTN compiler and subsequently sent to the Modelverse.
   When *model_code* is empty, an empty model is created.

   Examples:

   To create a new model called PetriNets, conforming to SimpleClassDiagrams, and load the model stored in models/PetriNets.mvc:
   .. code::
      >> model_add("PetriNets", "SimpleClassDiagrams", open("models/PetriNets.mvc", "r").read())

   To create a minimal instance of the language afterwards, which only contains a single place (and no attributes):
   .. code::
      >> model_add("my_pn", "PetriNets", """Place p1 {}""")

   To create a less minimal instance of the language, stored in models/my_pn2.mvc:
   .. code::
      >> model_add("my_pn2", "PetriNets", open("models/my_pn2.mvc", "r").read())

.. function:: upload_code(code)

   Upload a string of *code* in the Action Language formalism.
   This piece of code is compiled with the HUTN compiler and sent to the Modelverse directly.
   Makes the assumption that the **construct_function()** operation is currently running on the Modelverse, as otherwise the data will be misinterpreted.
   This is normally only useful in model transformations, where you want to upload a piece of code on-the-fly (e.g., adding a breakpoint in Action Language).

   Examples:

   To upload the file models/code.alc:
   .. code::
      >> upload_code(open("models/code.alc", "r").read())

   To upload a code fragment inline:
   .. code::
      >> upload_code("Void function a():\nreturn!")

.. function:: model_delete(model_name)

   Delete the model referred to by name *model_name*.
   This is a non-cascading delete, with almost no checks: model transformations depending on this model will likely become corrupted.

   Examples:

   To delete a previously created model:
   .. code::
      >> model_delete("my_pn2")

   Or to delete a metamodel, which is itself just a model:
   .. code::
      >> model_delete("PetriNets")

.. function:: model_list()

   Returns a list of all models existing in the Modelverse, together with their type.

   Examples:

   .. code::
      >> model_list()
      [("my_pn", "PetriNets"), 
       ("my_pn2", "PetriNets"),
       ("PetriNets", "SimpleClassDiagrams"),
       ("SimpleClassDiagrams", "SimpleClassDiagrams")]

.. function:: model_list_full()

   Returns a detailed list of all models existing in the Modelverse.
   This list includes information on permissions, owner, and group.

   Examples:

   .. code::
      >> model_list_full()
      [("my_pn", "PetriNets", "user1", "users", "200"), 
       ("my_pn2", "PetriNets", "user1", "users", "200"),
       ("PetriNets", "SimpleClassDiagrams", "user1", "users", "211"),
       ("SimpleClassDiagrams", "SimpleClassDiagrams", "admin", "admin", "211")]

.. function:: verify(model_name)

   Verify whether *model_name* conforms to its specified metamodel, as stored in the Modelverse.
   Returns either "OK" if the model conforms, or a string specifying the reason for non-conformance.

   Examples:

   When verifying a conforming model:
   .. code::
      >> verify("PetriNets")
      OK

   When verifying a non-conforming model:
   .. code::
      >> verify("my_pn")
      Lower cardinality violation for attribute "name" at Place p1.

.. function:: model_overwrite(model_name, new_model_code=None)

   Overwrites the model previously known under the name *model_name* with the model code in *new_model_code*.
   This operation differs from first deleting the model and then recreating it, as all metadata of the model is kept, such as access permissions.
   The new model can be kept empty, in which case the model will be cleared.

   Examples:

   To overwrite the PetriNets metamodel with a newer version, thereby also updating the metamodel of all existing instances ("my_pn" and "my_pn2"):
   .. code::
      >> model_overwrite("PetriNets", open("models/PetriNets2.mvc", "r").read())

   To overwrite an existing PetriNets instance:
   .. code::
      >> model_overwrite("my_pn", """Place p2 {}""")

.. function:: user_logout()

   Logs out the current user, thereby closing the task.
   Subsequent operations will no longer have any effect, as the task was terminated.
   To log in as a different user, the *init* operation has to be executed again.

   Examples:

   To log out the current user and allow future logins by this user:
   .. code::
      >> user_logout()

.. function:: user_delete()

   Delete the current user and thereafter log out.
   This removes the current user, making it impossible to log in as this user again.
   Existing models tied to this user, such as those the user is an owner of, remain bound to the (removed) user.
   While it is possible to recreate a new user with the same name, model permissions will not be inherited to this new user with the same name.

   Examples:

   To delete the current user, and make all owned models owner-less:
   .. code::
      >> user_delete()

.. function:: model_render(model_name, mapper_name)

   Render the model by name of *model_name* using the mapper by name of *mapper_name*.
   Both parameters have to be known models in the Modelverse.
   Outputs a JSON representation of the rendered model.
   This is basically just a shortcut for executing the specified operation and reading out the resulting model with a JSON representation.

   Examples:

   To render the PetriNets instance using the PetriNetsMapper:
   .. code::
      >> model_render("my_pn", "PetriNetsMapper")
      [{"id": "__12345", "type": "Ellipse", "x": 100, "y": 150, "height": 20, "width: "20"}]

.. function:: transformation_between(source, target)

   List all transformations that originate at *source* and end at *target*.
   Transformations can still be selected, even if they take more source models than those specified in the parameters.

   Examples:

   To fetch all endogenous transformations on PetriNets, assuming that some were previously defined:
   .. code::
      >> transformation_between("PetriNets", "PetriNets")
      ["PN_simulate", "PN_optimize"]

    To fetch all transformations from a DSL to PetriNets, assuming that multiple people created different denotational semantics:
    .. code::
       >> transformation_between("RPGame", "PetriNets")
       ["denotational1", "denotational_2", "denotational_3"]

.. function:: transformation_add_MT(source_metamodels, target_metamodels, operation_name, code, callback=lambda: None)

   Create a new model transformation operation.
   The new transformation takes *source_metamodels* as input, and generates *target_metamodels* as output.
   Both parameters are dictionaries of the form {name: metamodel_name}.
   The name is used later on in the model transformation as a prefix to the type.
   A single metamodel_name can be used for multiple names.
   Note that the target metamodel names may overlap with the source metamodel names, but the metamodel type should be identical.
   The operation is henceforth known by *operation_name* and is provided as a model in the string *code*.
   Optionally, a callback is defined which performs some operations on the merged metamodel, for example to define tracability links between (previously unrelated) metamodels.
   In the background, this operation does all necessary RAMification and model merging.

   Examples:

   To create a new model transformation for PetriNets simulation:
   .. code::
      >> transformation_add_MT({"pn": "PetriNets"}, {"pn": "PetriNets"}, "pn_simulate", open("models/PN_simulate.mvc", "r").read())

   To create a model transformation from a DSL to PetriNets, which requires tracability links:
   .. code::
      >> def tracability_links():
      >>     instantiate("Association", ID="Tile2Place", ("dsl/Tile", "pn/Place"))
      >>     instantiate("Association", ID="Dirrection2Transition", ("dsl/Direction", "pn/Transition"))
      >> transformation_add_MT({"dsl": "RPGame"}, {"pn": "PetriNets"}, "denotational_1", open("models/denotational_1.mvc", "r").read(), tracability_links)

   To create a multi-input model transformation:
   .. code::
      >> transformation_add_MT({"pn_1": "PetriNets", "pn_2": "PetriNets", "architecture: "Architecture"}, {"result": "PetriNets"}, "PN_merge", open("models/PN_merge.mvc", "r").read())

.. function:: transformation_add_AL(source_metamodels, target_metamodels, operation_name, code, callback=lambda: None)

   Creates a new action language operation.
   Similar to *transformation_add_MT*, but now does not require RAMification.
   The *code* parameter also is not specified as a Modelverse model (.mvc), but as action language (.alc).

   Examples:

   To create a new action language operation for PetriNets reachability analysis:
   .. code::
      >> transformation_add_AL({"pn": "PetriNets"}, {"graph": "ReachabilityGraph"}, "pn_analyze", open("models/PN_reachability.alc", "r").read())

   To create an action language operation from a Scheduling DSL to a list, which requires tracability links:
   .. code::
      >> def tracability_links():
      >>     instantiate("Association", ID="Task2Event", ("schedule/Task", "list/Event"))
      >> transformation_add_AL({"schedule": "SchedulingDSL"}, {"list": "EventList"}, "sequentialize", open("models/sequentialize_schedule.alc", "r").read(), tracability_links)

.. function:: transformation_add_MANUAL(source_metamodels, target_metamodels, operation_name, callback=lambda: None)

   Creates a new manual operation.
   Identical to *transformation_add_AL*, but does not take any code as content.

   Examples:

   To create a manual refinement operation on PetriNets:
   .. code::
      >> transformation_add_MANUAL({"pn": "PetriNets"}, {"pn": "PetriNets"}, "pn_refine")

   To create a multi-input refinement operation on PetriNets:
   .. code::
      >> transformation_add_MANUAL({"pn": "PetriNets", "requirements": "Requirements"}, {"pn": "PetriNets"}, "pn_refine_req")

.. function:: transformation_execute_AL(operation_name, input_models_dict, output_models_dict, callback=lambda i: None)

   Executes the Action Language model *operation_name* with *input_models_dict* as inputs and *output_models_dict* as outputs.
   For both dicts, the contents describe the mapping between the parameter names of the operation to the names in the Modelverse.
   Values in *input_models_dict* must be existing models, whereas values in *output_models_dict* can be non-existing upon invocation.
   A *callback* function can be defined when the action language model requires user input or output.
   This callback function can be used to communicate with the executing action language directly.

   Examples:

   To execute reachability analysis on an existing petri net:
   .. code::
      >> transformation_execute_AL("pn_analyze", {"pn": "my_pn"}, {"graph": "my_pn_reachability"})

   To execute reachability analysis which prompts the user, for example because it is a debugging prompt:
   .. code::
      >> def callback(value):
      >>     print(value)
      >>     return raw_input()
      >> transformation_execute_AL("pn_simulate", {"pn": "my_pn"}, {"graph": "my_pn_reachability"}, callback)
      << Which operation do you want to execute?
      >> step
      << Step performed! New operation?
      >> continuous
      << Finished analysis!

.. function:: transformation_execute_MANUAL(operation_name, input_models_dict, output_models_dict, callback=lambda i: None)

   Executes the manual model operation *operation_name*.
   Furthermore, this is identical to *transformation_execute_AL*, with the exception of the *callback* function.
   In this case, the callback function can be just another series of Modelverse operations, though pertaining to a single model.
   As such, the *model_name* parameter of these operations **MUST** be set to *None*.

   Examples:

   To execute a manual operation, which requires you to refine a PetriNets instance:
   .. code::
      >> def callback():
      >>     p1 = instantiate(None, "pn/Place")
      >>     t1 = instantiate(None, "pn/Transition")
      >>     instantiate(None, "pn/P2T", (p1, t1))
      >> transformation_execute_MANUAL("pn_refine", {"pn": "my_pn"}, {"pn": "my_pn"}, callback)

.. function:: transformation_execute_MT(operation_name, input_models_dict, output_models_dict, callback=lambda i: None)

   Executes the model transformation operation *operation_name*.
   Identical to *transformation_execute_AL*.

   Examples:

   To execute a model transformation on a PetriNets instance, thereby putting the result in a different model:
   .. code::
      >> transformation_execute_MT("pn_simulate", {"pn": "my_pn"}, {"pn": "my_simulated_pn"})

    To execute a model transformation which prompts the user:
    .. code::
       >> def callback(value):
       >>     print(value)
       >>     return raw_input()
       >> transformation_execute_MT("pn_simulate_prompt", {"pn": "my_pn"}, {"pn": "my_simulated_pn"}, callback)

.. function:: transformation_list()

   Returns a list of all operations specified in the Modelverse, together with their type.

   Examples:

   To fetch a list of all transformations and their type of operation:
   .. code::
      >> transformation_list()
      [("pn_simulate", "ModelTransformation"),
       ("pn_reachability", "ActionLanguage"),
       ("pn_simulate_prompt", "ModelTransformation"),
       ("pn_refine", "ManualOperation")]

.. function:: process_execute(process_name, prefix, callbacks)

   Execute the process model stored as *process_name*.
   All models are stored with their names prefixed with *prefix* to allow for multiple executions of the same model.
   Note that this applies to the resolution of input models as well.
   Optionally, a dictionary of *callbacks* can be defined with as key the operation that is being executed, and value the actual callback.
   The callbacks must be similarly defined just like how they were defined in the individual *transformation_execute* operations.

   Examples:

   To execute a process model for the power window example:
   .. code::
      >> process_execute("pm_powerwindow", "pw_")

   To execute a process model for the power window example, which requires user input for some operations:
   .. code::
      >> def refine_architecture():
      >>     # Do some operation on the architecture model here
      >>     node1 = instantiate(None, "Node")
      >>     node2 = instantiate(None, "Node")
      >>     instantiate(None, "Connection", (node1, node2))
      >> def refine_control():
      >>     # Do some operation on the control model here
      >>     s1 = instantiate(None, "State")
      >>     s2 = instantiate(None, "State")
      >>     instantiate(None, "Transition", (s1, s2))
      >> def refine_query():
      >>     # Do some operation on the safety query model here
      >>     p1 = instantiate(None, "Place")
      >>     attr_assign(None, p1, "tokens", 2)
      >> process_execute("pm_powerwindow", "pw_", {"refine_plant": refine_plant, "refine_control": refine_control, "refine_query": refine_query})

.. function:: permission_modify(model_name, permissions)

   Change the permissions of *model_name* to *permissions*.
   The permissions is a string of three characters, each between 0 and 2.
   The format is similar to the UNIX permission system: the leftmost character is the permission for the owning user, the middle character for members of the ownin group, and the rightmost character for all other users.
   Character 0 signifies no access, 1 read-only access, and 2 full read/write access.
   Note that changing permissions trickle down to the instances as well: if the metamodel is no longer readable to the user, all models conforming to it become unreadable in this specific context.

   Examples:

   To modify the permissions of the PetriNets metamodel, allowing only the owner to read and write to it:
   .. code::
      >> permission_modify("PetriNets", "200")

   To modify the permissions of a PetriNets model, granting everyone read/write access:
   .. code::
      >> permission_modify("PetriNets", "222")

.. function:: permission_owner(model_name, owner)

   Change the owner of the model *model_name* to *owner*.
   Changing permissions trickles down to the instances as well: if the metamodel is no longer readable to the user, all models conforming to it become unreadable in this specific context.

   Examples:

   To change the owning user of the PetriNets metamodel to user2:
   .. code::
      >> permission_owner("PetriNets", "user2")

.. function:: permission_group(model_name, group)

   Change the owning group of the model *model_name* to *group*.
   The same remarks hold as for all other permission operations.

   Examples:

   To change the owning group of the PetriNets metamodel to group1:
   .. code::
      >> permission_group("PetriNets", "group1")

.. function:: group_create(group_name)

   Create a new group named *group_name*.
   You automatically become an administrator for this group.

   Examples:

   To create a new group called group2:
   .. code::
      >> group_create("group2")

.. function:: group_delete(group_name)

   Delete the group named *group_name*.
   All users will automatically be kicked from the group, and all permissions previously granted by this group become void.

   Examples:

   To delete the group group2
   .. code::
      >> group_delete("group2")

.. function:: group_owner_add(group_name, user_name)

   Add user *user_name* as an owner of group *group_name*.
   This automatically makes the user join the specified group if this was not yet the case.

   Examples:

   To add user user1 as a new owner, or group administrator, to group group1:
   .. code::
      >> group_owner_add("group1", "user1")

.. function:: group_owner_delete(group_name, user_name)

   Remove user *user_name* as an owner of group *group_name*.

   Examples:

   To delete user1 as an owner, or group administrator, from group group1:
   .. code::
      >> group_owner_delete("group1", "user1")

.. function:: group_join(group_name, user_name)

   Have user *user_name* join the group *group_name* as an ordinary user.

   Examples:
   
   To make user user1 join the group group1, of which the current user is an owner:
   .. code::
      >> group_join("group1", "user1")

.. function:: group_kick(group_name, user_name)

   Remove user *user_name* from the group *group_name*.
   If the user was an owner of the group, these permissions are also revoked.

   Examples:

   To kick user user1 from group group1, of which the current user is an owner:
   .. code::
      >> group_kick("group1, "user1")

.. function:: admin_promote(user_name)

   Promote user *user_name* to admin status.
   Admin status grants users access to all operations, and provides all permission.
   Effectively, all groups and files have read/write access for the admin user, independent of the stored permissions.

   Examples:

   To promote user1 to admin states:
   .. code::
      >> admin_promote("user1")

.. function:: admin_demote(user_name)

   Demote user *user_name* to ordinary user.

   Examples:

   To demote user1 to a normal user:
   .. code::
      >> admin_demote("user1")

.. function:: element_list(model_name)

   Returns a list of all elements and their type specified in the model named *model_name*.
   This list can contain much more than only simple elements, but includes anonymous edges and attributes as well.
   It is therefore not recommended for general purpose use; use *element_list_nice* instead.

   Examples:

   To get a list of all elements in the PetriNets metamodel:
   .. code::
      >> element_list("PetriNets")
      [("Place", "Class"),
       ("Transition", "Class"),
       ("P2T", "Association"),
       ("T2P", "Association"),
       ...]

.. function:: types(model_name)

   Returns a list of all types usable in the model named *model_name*.
   This is similar to executing *element_list* on the metamodel of this model.
   It attempts to filter out most unusable elements.

   Examples:

   To get a list of all types usable in the PetriNets metamodel (i.e., when altering the metamodel itself):
   .. code::
      >> types("PetriNets")
      ["Class", "Association", "SimpleAttribute", ...]

.. function:: types_full(model_name)

   Returns a list of all types usable in the model named *model_name*.
   In contrast to *types*, this includes hidden elements as well (i.e., those starting with __)

   Examples:

   To get a list of all types usable in the PetriNets metamodel (i.e., when altering the metamodel itself):
   .. code::
      >> types("PetriNets")
      ["Class", "Association", "SimpleAttribute", "__12345", ...]

.. function:: read(model_name, ID)

   Read the content of model element *ID* in model *model_name*.
   This returns the type of the element, and the set of source and destination if the element is an edge (*None* otherwise).

   Examples:

   To read out the P2T link in the PetriNets metamodel:
   .. code::
      >> read("PetriNets", "P2T")
      ["Association", ("Place", "Transition")]

   To read out the Place node in the PetriNets metamodel:
   .. code::
      >> read("PetriNets", "Place")
      ["Class", None]

   To read out some P2T instance in a PetriNets model:
   .. code::
      >> read("my_pn", "p1_to_t1")
      ["P2T", ("p1", "t1")]

   To read out some Place instance in a PetriNets model:
   .. code::
      >> read("my_pn", "p1")
      ["Place", None]

.. function:: read_attrs(model_name, ID)

   Return a dictionary of all attributes of model element *ID* in model *model_name*, containing their values.
   All values in the Modelverse are primitive types, and as such, this is also the case in this operation.
   The value is *None* in case the attribute is not set.

   Examples:

   To read out the attributes of the Place class:
   .. code::
      >> read_attrs("PetriNets", "Place")
      {"lower_cardinality": None, "upper_cardinality": None}

   To read out the attributes of a Place instance:
   .. code::
      >> read_attrs("my_pn", "p1")
      {"name": "critical_section", "tokens": 1}

.. function:: instantiate(model_name, typename, edge=None, ID="")

   Instantiate a new instance of *typename* in the model *model_name*.
   If the instance is an edge, provide a tuple containing the source and target as *edge*.
   A preferred *ID* can be specified, though there is no guarantee that this name is actually used (e.g., if it is already taken by another element).
   This operation returns the actually assigned ID.
   It is this ID that is used for all other operations on the model.

   Examples:

   To create a new Place instance in a PetriNets model:
   .. code::
      >> instantiate("my_pn", "Place")
      "__12345"

   To create a new Place instance with a preferred ID, which is granted:
   .. code::
      >> instantiate("my_pn", "Place", ID="critical_section")
     "critical_section"

   To create a new Place instance with a preferred ID, which is not granted:
   .. code::
      >> instantiate("my_pn", "Place", ID="critical_section")
     "critical_section_12345"

   To create a new P2T instance in a PetriNets model:
   .. code::
      >> instantiate("my_pn", "P2T", ("p1", "t1"))
      "__12345"

   To create a new concept in the PetriNets metamodel, which can later on be used:
   .. code::
      >> instantiate("PetriNets", "Association", ("Place", "Transition"), ID="InhibitorArc")
      "InhibitorArc"
      >> instantiate("my_pn", "InhibitorArc", ("p1", "t1"))
      "__12345"

.. function:: delete_element(model_name, ID)

   Delete the element *ID* in the model *model_name*.
   This is a recursive delete, and all incoming and outgoing edges will be removed (recursively) as well.

   Examples:

   To delete an existing element in a PetriNets model:
   .. code::
      >> delete_element("my_pn", "critical_section")

   To delete an existing exdge in a PetriNets model:
   .. code::
      >> delete_element("my_pn", "p1_to_t1")

    When deleting an element "p1", the arc "p1_to_t1" is also removed automatically.
    .. code::
       >> delete_element("my_pn", "p1")
       >> delete_element("my_pn", "p1_to_t1") # <-- Raises an exception: arc is already removed

.. function:: attr_assign(model_name, ID, attr, value)

   Assign the value *value* to the attribute named *attr* of the element *ID* in the model named *model_name*.
   If the attribute already has an assigned value, the previous value is removed first.

   Examples:

   To assign some attributes to a Place instance:
   .. code::
      >> attr_assign("my_pn", "p1", "name", "my first place")
      >> attr_assign("my_pn", "p1", "tokens", 1)

   To assign some attributes to the Place class itself:
   .. code::
      >> attr_assign("PetriNets", "Place", "upper_cardinality", 1)

.. function:: attr_assign_code(model_name, ID, attr, code)

   Assign the code block *code* to the attribute named *attr* of the element *ID* in the model named *model_name*.
   If the attribute already has an assigned value, the previous value is removed first.
   The assigned code is compiled to Action Language by the HUTN compiler.

   Examples:

   To assign a piece of action code to a Statecharts transition, loaded from file:
   .. code::
      >> attr_assign_code("my_sc", "t1", "script", open("models/t1_script", "r").read())

   To assign a piece of action code to a Statecharts transition, defined inline
   .. code::
      >> code = \
      >>   """
      >>   Void function action(attributes : Element):
      >>        dict_overwrite(attributes, "counter", 1)
      >>        return!
      >>   """
      >> attr_assign_code("my_sc", "t1", "script", code)

.. function:: attr_delete(model_name, ID, attr)

   Unset the attribute *attr* of model element *ID* in the model *model_name*.
   This is not necessary when assigning a new value, as *attr_assign* automatically does this when required.
   As such, this only is useful when dealing with an optional attribute, or when you want to create a non-conforming model.

   Examples:

   To unset the name attribute of a place
   .. code::
      >> attr_delete("my_pn", "p1", "name")

.. function:: read_outgoing(model_name, ID, typename)

   Returns a list of all outgoing associations of *ID*, typed by *typename*, in model *model_name*.
   Typename can be set to the empty string to indicate that all types must match.
   Note that this returns the association itself, **NOT** the destination.

   Examples:

   To get all arcs starting in place p1:
   .. code::
      >> read_outgoing("my_pn", "p1", "P2T")
      ["p1_to_t1"]

   To get all allowed connections starting in a Place:
   .. code::
      >> read_outgoing("PetriNets", "Place", "Association")
      ["P2T", "InhibitorArc"]

.. function:: read_incoming(model_name, ID, typename)

   Returns a list of all incoming associations of *ID*, typed by *typename*, in model *model_name*.
   Typename can be set to the empty string to indicate that all types must match.
   Note that this returns the association itself, **NOT** the source.

   Examples:

   To get all arcs going to place p1:
   .. code::
      >> read_incoming("my_pn", "p1", "T2P")
      ["t1_to_p1"]

   To get all allowed connections going to a Place:
   .. code::
      >> read_incoming("PetriNets", "Place", "Association")
      ["T2P"]

.. function:: read_association_source(model_name, ID)

   Returns the identifier of the source of association *ID* in model *model_name*.

   Example:

   To read out the source of the P2T link:
   .. code::
      >> read_association_source("PetriNets", "P2T")
      "Place"

   To read out the source of an arc:
   .. code::
      >> read_association_source("my_pn", "p1_to_t1")
      "p1"

.. function:: read_association_destination(model_name, ID)

   Returns the identifier of the target of association *ID* in model *model_name*.

   Example:

   To read out the target of the P2T link:
   .. code::
      >> read_association_destination("PetriNets", "P2T")
      "Transition"

   To read out the target of an arc:
   .. code::
      >> read_association_destination("my_pn", "p1_to_t1")
      "t1"

.. function:: service_register(name, function)

.. function:: service_stop()

.. function:: service_get(port)

.. function:: service_set(port, value)

.. function:: user_password(user, password)

.. function:: transformation_read_signature(transformation)

.. function:: element_list_nice(model_name)

.. function:: connections_between(model_name, source_element, target_element)

.. function:: define_attribute(model_name, node, attr_name, attr_type)

.. function:: all_instances(model_name, type_name)

Exceptions
^^^^^^^^^^

Below is a list of all exceptions that the wrappers can raise, together with a summary of the kind of error that occured.

.. exception:: ModelverseException

   Generic Modelverse Exception, of which all others inherit.
   This should be the only type of exception that the wrapper can raise.

.. exception:: UnknownError

   Unknown exception has occured.
   This is likely something wrong with the connection, such as the Modelverse that suddenly disconnected.

.. exception:: UnknownIdentifier

   The specified identifier could not be resolved in the Modelverse.

.. exception:: UnknownType

   The specified identifier could not be resolved as a type in the Modelverse.

.. exception:: NotAnAssociation

   The specified identifier does not resolve to an association (or edge), even though this was intended.

.. exception:: UnsupportedValue

   The specified value is not a primitive that can be serialized.
   Supported types are: string, boolean, integer, float, and action.

.. exception:: CompilationError

   Error in the HUTN compiler during compilation.

.. exception:: NoSuchAttribute

   The specified attribute does not exist for this element.

.. exception:: UnknownModel

   The specified model can not be resolved in the Modelverse.

.. exception:: ConnectionError

   Error with the connection to the Modelverse.

.. exception:: ModelExists

   The identifier to give to the newly created model already exists.

.. exception:: PermissionDenied

   Permission denied to either write or read the specified resource.

.. exception:: InvalidMode

   An operation was executed in the wrong context.
   For example, all operations are only valid after a successful *init* and *login* call.

.. exception:: InterfaceMismatch

   The Modelverse responded with an unexpected response.
   As a response came, the Modelverse is likely still running, though we have no idea how to interpret the result.
   Likely, the wrapper is not up to date with the latest Modelverse operations.

Custom
------

Other wrappers can be made as desired, in whatever language required.
This is due to the fact that the Modelverse communicates only through XML/HTTPRequests.
As such, all languages that support this, can simply mimic the interface used by any of the implemented wrappers.