Documentation changes for doc site

Author: mikeWShef

CONTRIBUTING.rst

@@ -80,19 +80,18 @@ Ready to contribute? Here's how to set up `slippy` for local development.
 
    Now you can make your changes locally.
 
-5. When you're done making changes, check that your changes pass flake8 (code style checks) and the
-   tests, including testing other Python versions with tox::
+5. When you're done making changes, check that your changes pass flake8 (code style), the tests (code functionality) and test that the documentations will still compile::
 
     $ flake8 slippy tests
     $ python setup.py test or pytest
-    $ tox
+    $ sphinx-build doc build
 
-   To get flake8 and tox, just pip install them into your virtualenv.
+   To get flake8, pytest and sphinx, just pip install them into your virtualenv.
 
 6. Commit your changes and push your branch to GitHub::
 
     $ git add .
-    $ git commit -m "Your detailed description of your changes."
+    $ git commit -m "A detailed description of your changes."
     $ git push origin name-of-your-bugfix-or-feature
 
 7. Submit a pull request through the GitHub website.
@@ -106,8 +105,9 @@ Before you submit a pull request, check that it meets these guidelines:
    the bug which was fixed, this will ensure that it is not accidentally
    broken in future releases.
 2. If the pull request adds functionality, the docs should be updated. Put
-   your new functionality into a function with a docstring, and add the
-   feature to the list in README.rst.
+   your new functionality into a function or class with a docstring, add a reference
+   to it in the docstring of slippy.surface.__init__.py or slippy.contact.__init__.py
+   and add the feature to the list in README.rst.
 3. Flake8 and pytest tests all pass, please run tests locally to reduce the
    load/ cost of the automated testing service.
 
@@ -119,7 +119,6 @@ Make sure all your changes are committed (including an entry in HISTORY.rst).
 Then run::
 
 $ bump2version patch # possible: major / minor / patch
-$ git push
-$ git push --tags
+$ git push --follow-tags
 
 Travis will then deploy to PyPI if tests pass.

README.rst

@@ -150,7 +150,7 @@ A more detailed description of the decisions behind the code can be found in the
     my_model.add_step(my_step)
 
     # add sub models
-    wear_submodel = c.sub_models.EPPWear('wear_l', 0.5, True)
+    wear_submodel = c.sub_models.WearElasticPerfectlyPlastic('wear_l', 0.5, True)
     my_step.add_sub_model(wear_submodel)
 
     # add output requests

doc/conf.py

@@ -33,7 +33,6 @@
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
 extensions = [
     'sphinx.ext.autodoc',
-    'sphinx.ext.intersphinx',
     'sphinx.ext.viewcode',
     'sphinx.ext.autosummary',
     'sphinx.ext.napoleon',

doc/contact_models.rst

@@ -0,0 +1,83 @@
+.. _ContactModels:
+
+
+Contact Models
+==============
+
+Slippy can solve rough surface contact problems with the boundary element method, based on the half space approximation.
+In order to access this functionality you should make and solve a contact model which describes the problem you want to model.
+When solved this model will run through each of the steps it contains, first solving the main problem described by the step then solving all the sub-models and outputs required.
+This process is shown in the image below.
+
+|solution|
+
+Making a contact model has several steps but a common work flow can be used for a wide variety of simulations.
+
+Define surface geometry
+-----------------------
+
+A contact model requires two surfaces to be defined. The first surface should also be descretised on a grid which will
+form the mesh for the solution. Some sub models will also require the second surface to be descretised on a grid so
+that processes such as wear can be applied.
+
+Define materials
+----------------
+
+The material properties of each of the surfaces must be defined by making material objects and assigning them to the surfaces.
+These objects both describe how the materials deform (eg elastic) and also provide the computational back end for solving the contact.
+
+At this stage if the contact is lubricated the properties of the lubricant should also be defined.
+
+Make contact model
+------------------
+
+Now you are ready to make a contact model object, to do this you simply pass the surfaces and the lubricant to the constructor.
+This will make a new contact model object, but at this stage it is an empty shell, that will not do anything when solved.
+
+Make a model step
+-----------------
+
+A model step describes a contact problem to solve, this might be the normal load between the surfaces and / or the tangential displacement.
+More formally the step should include processes which must be two way coupled to the contact mechanics solution.
+So, for example, for an EHL problem an appropriate step must be selected which will solve the fluid pressure problem and the deformation problem at the same time.
+
+Add sub models
+--------------
+
+Sub - models can solve any additional behaviour which only needs to be one way coupled to the behaviour in the step.
+This typically includes things which change more slowly over time, such as wear processes.
+They can also be used to calculate output parameters, thus reducing the size of output files.
+
+Add step to model
+-----------------
+
+When the step has been made and the sub model have been added, the step can be added to the model.
+By default steps are solved in the order they are added, however this can be over ridden if needed.
+
+Add output requests
+-------------------
+
+A model in slippy may have several steps, each of these may may have many time steps. Writing the entire state of the
+model to file for each time step would be time consuming and result in very large output files.
+To solve this problem slippy has an output request system which can be used to save output parameters at set time points.
+If simulations are longer than one time step this should be used to save intermediate states.
+
+Checking the model
+------------------
+
+As an optional measure you can check the model before running.
+This will ensure that the surface are properly defined, with materials.
+It will also check that parameters which are required for sub-models to run will be present in the model state when the sub-model is executed.
+This can save errors in execution. Lastly, it will also check that all requested outputs will be available when they are to be written.
+If an output cannot be found it will silently error, meaning that the model will not stop execution, but the output will not be present in the output file.
+
+Solve model
+-----------
+
+The final step is to solve the model this will run thorough the steps in order, solving the main contact mechanics problem,
+followed by the sub models and finally writing the requested outputs.
+The output database can be read in by using the OutputReader object in slippy.contact.
+
+.. |solution| image:: solving.svg
+        :alt: Solving schematic
+        :target: https://github.com/FrictionTribologyEnigma/slippy

doc/examples.rst

@@ -3,12 +3,18 @@
 Examples
 ========
 
-This file contains links to live code notebooks with examples for most of the functionality in slippy. The notebooks will run in your browser, but the code can be copy pasted into a text file to run locally. For more specific examples of how to use each function or class try the API reference.
+We have included many examples of common tasks, these are a good place to start with writing your own code for problems or to clarify something which is not clear in the documentation.
+The examples can be viewed online in the github `repository`_.
+They can also be downloaded and run locally on your own computer, however this will also require that jupyter is installed.
 
-Surface
--------
+If you have followed the installation instructions you can install jupyter using pip:
 
+    python -m pip install jupyter
 
+you can then run jupyter:
 
-Contact
--------
+    jupyter notebook
+
+This will open a notebook page in your browser, you can use this to open and run the example files from github
+
+.. _repository: https://github.com/FrictionTribologyEnigma/slippy/tree/master/examples

doc/extensions.rst

@@ -0,0 +1,70 @@
+.. _Extensions:
+
+Extensions
+==========
+
+Slippy is built to be simple to extend. This means that, if done correctly, new functionality can be added that works with existing code.
+However it can ber difficult to see how a new model can fit in. Typically adding functionality would involve making a new sub class for one of the base classes below.
+
+Note that these base classes can change without breaking compatibility with the users code, however these changes may break compatibility with extensions.
+If your extension has been added to the main code, it will not be broken by future updates.
+In general we will try to add depreciation warnings and make updates simple for user built extensions.
+However it is worth keeping a record of the version of slippy that your extension was developed for as this version will always be available on pypi.
+
+Surface profiles
+----------------
+
+New profile types can be added by sub classing the _AnalyticalSurface abstract base class found in slippy.surface.
+To implement a new analytically defined surface type you must implement the __init__ and _height methods.
+The __init__ method should include a call to the super's init:
+
+    super().__init__(generate=generate, rotation=rotation, shift=shift,
+                     grid_spacing=grid_spacing, extent=extent, shape=shape)
+
+The _height method should take as arguments an array of x coordinates and an array of y coordinates and return the height of the profile at the specified points.
+
+Materials
+---------
+
+If the influence matrix for a material is known, then to add it into slippy the _IMMaterial base class can be sub classed.
+This requires the user to implement the __init__ and influence_matrix methods.
+Practically it is also useful to memoize the influence matrix to save computing it for every time step of a simulation.
+
+Steps
+-----
+
+Implementing a new model step is a major task, it requires the use to implement the __init__ and solve methods.
+Each step must also have a .provides property which details what will be in the state dict at the end of the execution
+For a clear picture of what a step should do have a look at the existing StaticStep and QuasiStaticStep.
+Both of these sub class the _ModelStep abstract base class from slippy.abcs.
+
+The results from each step of the simulation are passed around in a dictionary. Each step has a .provides property
+which is a set of strings, these string are exactly and only the keys to the current state dictionary at the end of the
+step. Many common items have names which should be respected if your new step is to work with existing sub models.
+If your step provides additional parameters these should be given descriptive names.
+In general parameters should be a single value or an array of values, anything else requires special treatment by the output system.
+For example to store a set of coordinates points_x and points_y should be used rather than a single points parameter being a list of arrays.
+
+If your step promises to provide something which it doesn't actually provide or provides extra parameters, slippy will raise an error when the model is solved.
+This is intended to push errors into the development process and ultimately leave fewer confused users.
+As such the provides property can be set by the init method and doesn't need to be the same for every possible version of the step.
+
+Steps should include calls to: self.solve_sub_models and self.save_outputs after the main problem has been solved.
+
+Sub models
+----------
+
+Making a new sub model is a simple task. The _SubModel abstract base class from slippy.abcs should be used.
+To add a sub model the __init__ and solve methods must be implemented.
+As above, a call to the super's init method should be included in the __init__ method:
+
+    super().__init__(name, requires, provides)
+
+This sets the name which should be a string, and the requires and provides properties of the sub model.
+The requires and provides properties should be sets of strings. The requires property should include every item which
+must be in the current state dict for the sub model to be executed successfully.
+The provides property should detail exactly and only what the sub model will add to the current state dict.
+Unexpected or missing items will cause an error when the model is solved.
+
+As well as the current state each sub model has access to the main model and thus the surface profiles of each surface.
+Because of this sub models can be used to apply wear to the surfaces. Other parameters can be retained by the sub model.

doc/generated/slippy.contact.ContactModel.rst

@@ -1,4 +1,4 @@
-slippy.contact.ContactModel
+slippy.contact.ContactModel
 ===========================
 
 .. currentmodule:: slippy.contact
@@ -14,6 +14,7 @@ slippy.contact.ContactModel
    .. autosummary::
 
       ~ContactModel.__init__
+      ~ContactModel.add_output
       ~ContactModel.add_step
       ~ContactModel.data_check
       ~ContactModel.solve
@@ -26,8 +27,8 @@ slippy.contact.ContactModel
 
    .. autosummary::
 
+      ~ContactModel.adhesion
       ~ContactModel.log_file_name
       ~ContactModel.lubricant_model
-      ~ContactModel.output_file_name
 
 

doc/generated/slippy.contact.Elastic.rst

@@ -1,4 +1,4 @@
-slippy.contact.Elastic
+slippy.contact.Elastic
 ======================
 
 .. currentmodule:: slippy.contact
@@ -15,7 +15,6 @@ slippy.contact.Elastic
 
       ~Elastic.__init__
       ~Elastic.displacement_from_surface_loads
-      ~Elastic.guess_loads_from_displacement
       ~Elastic.influence_matrix
       ~Elastic.loads_from_surface_displacement
       ~Elastic.speed_of_sound