Add CONTRIBUTING.md and list of papers (#15)

CONTRIBUTING.md

@@ -0,0 +1,64 @@
+# Contributing to `piglot`
+
+Thank you for considering contributing to `piglot`!
+We appreciate your interest in helping us improve our project.
+
+## How to Contribute
+
+To contribute to `piglot`, please follow these steps:
+
+1. Fork the repository and create a new branch for your contribution.
+2. Make your changes or additions to the codebase.
+3. Write tests to ensure the correctness of your changes.
+4. Run the existing tests to make sure they pass.
+5. If relevant, build a set of appropriate examples for the new features and add them to the documentation.
+6. Commit your changes and push them to your forked repository.
+7. Submit a pull request to the main repository.
+
+### Tests
+
+When contributing with new features, also write tests for them in the `test` directory.
+We use `pytest` for this task in our CI framework.
+While we currently don't have strict test coverage requirements, new features should be extensively tested.
+
+### Examples
+
+We strongly encourage contributors to also build minimal working examples (MWEs) for new features or solvers.
+These should be placed inside the `examples` directory, along with the required additional files.
+A description of the example should also be added to the `docs/source/examples` directory, showing the usage and results of your example.
+Don't forget to add a reference to the indices in `docs/source/examples/*.rst`.
+
+### Input file templates
+
+If your new features require modifications to the `.yaml` configuration specification, these changes should be included in the input file templates.
+These are hosted in the `examples/templates` directory, which are then loaded by the documentation in `docs/source/templates`.
+If you add new solvers or optimisers, please update both locations with your new template.
+
+## Code Style
+
+Please adhere to the following code style guidelines when contributing to `piglot`:
+
+- Use spaces for indentation. We are using 4 spaces.
+- Follow the naming conventions used in the existing codebase.
+- Write clear and concise comments to explain your code.
+- Write docstrings for every module, method and class. We use the `numpy` docstring style.
+
+We use `flake8` for linting the code.
+Please refer to our configuration (`.flake8` in the repo root) for additional details.
+Compliance with this is enforced in our CI procedure.
+
+## Reporting Issues
+
+If you encounter any issues or have suggestions for improvement, please open an issue on the [issue tracker](https://github.com/CM2S/piglot/issues).
+Provide as much detail as possible to help us understand and address the problem.
+
+## Papers using `piglot`
+
+If you use `piglot` in your work, we encourage you to add your contribution to the [list of papers](docs/source/papers.md) using `piglot`.
+Feel free to open a PR for adding an entry to that list!
+
+## License
+
+By contributing to `piglot`, you agree that your contributions will be licensed under the [MIT License](https://opensource.org/licenses/MIT).
+
+We look forward to your contributions! Thank you for your support.

README.md

@@ -26,7 +26,10 @@ The primary emphasis is on derivative-free optimisation, ensuring compatibility
 * **Optimisation algorithms:** Off the shelf, there are several optimisers included in the package. Among them, we highlight our fully-fledged Bayesian optimisation (based on [BoTorch](https://botorch.org/)) that supports optimising stochastic and composite objectives and is highly customisable. Additional methods can also be easily implemented within `piglot`.
 * **Visualisation tools:** You can use the built-in tool `piglot-plot` to visualise the results of the optimisation. There are native plotting utilities for the optimised responses, the parameter history, objective history and, for supported solvers, live plotting of the currently running case. Also, an animation of the optimisation process can be exported.
 
-Feel free to explore, contribute, and optimize with `piglot`!
+Feel free to explore, [contribute](CONTRIBUTING.md), and optimise with `piglot`!
+We recommend starting by reading the [Getting started](#getting-started) section, and then checking the latest [documentation](https://piglot.readthedocs.io) for additional details.
+You can use our [discussions](https://github.com/CM2S/piglot/discussions) page for help and our [issue tracker](https://github.com/CM2S/piglot/issues) for reporting problems and suggestions.
+If you use this tool in your work, we encourage to open a PR to add it to our [list of papers](docs/source/papers.md).
 
 
 # Getting started
@@ -39,7 +42,9 @@ There are two modes of operation available: running using the given `piglot` and
 We use YAML configuration files to specify the optimisation problem to solve.
 This is the simplest form of using `piglot` and is the recommended approach unless you have a strong motive to use Python scripts (described [here](#using-python-scripts)).
 A simple analytical curve fitting problem is included to showcase how to use configuration files.
-In this case, we fit a quadratic expression of the type $f(x) = a x^2$.
+
+To keep things simple, in this case, we fit a quadratic expression of the type $f(x) = a x^2$.
+Note that this curve is generally obtained from a physics-based solver when solving an inverse problem.
 As a reference, a numerically generated reference from the expression $f(x) = 2 x^2$ is used (provided in the `examples/sample_curve_fitting/reference_curve.txt` file).
 We want to find the value for $a$ that better fits our reference (it should be 2).
 The configuration file for this example is:

docs/source/index.rst

@@ -46,8 +46,10 @@ We highlight:
 - **Optimisation algorithms:** Off the shelf, there are several optimisers included in the package. Among them, we highlight our fully-fledged Bayesian optimisation (based on `BoTorch <https://botorch.org/>`_) that supports optimising stochastic and composite objectives and is highly customisable. Additional methods can also be easily implemented within :code:`piglot`.
 - **Visualisation tools:** You can use the builtin tool :code:`piglot-plot` to visualise the results of the optimisation. There are native plotting utilities for the optimised responses, the parameter history, objective history and, for supported solvers, live plotting of the currently running case. Also, an animation of the optimisation process can be exported.
 
-Feel free to explore, contribute, and optimize with :code:`piglot`!
-
+Feel free to explore, `contribute <CONTRIBUTING.md>`_, and optimise with :code:`piglot`!
+We recommend starting by reading the `Getting started <https://github.com/CM2S/piglot?tab=readme-ov-file#getting-started>`_ section, and then checking the latest `documentation <https://piglot.readthedocs.io>`_ for additional details.
+You can use our `discussions <https://github.com/CM2S/piglot/discussions>`_ page for help and our `issue tracker <https://github.com/CM2S/piglot/issues>`_ for reporting problems and suggestions.
+If you use this tool in your work, we encourage to open a PR to add it to our list of papers.
 
 Installation
 ------------
@@ -118,7 +120,8 @@ If you wish to install all optimisers at once, you can run :code:`pip install pi
 
 .. toctree::
    :maxdepth: 1
-   :caption: API
+   :caption: Reference
    :hidden:
 
-   Reference <_autosummary/piglot>
+   API <_autosummary/piglot>
+   Papers <papers.md>

docs/source/papers.md

@@ -0,0 +1,5 @@
+# Papers using `piglot`
+
+- [Efficient constitutive parameter identification through optimisation-based techniques: A comparative analysis and novel composite Bayesian Optimisation Strategy](https://dx.doi.org/10.2139/ssrn.4674421). Rui Pedro Cardoso Coelho, Ana Francisca Carvalho Alves and Francisco Manuel Andrade Pires. SSRN 2023.
+- [A multi-scale model combining martensitic transformations with multi-phase crystallographic slip](https://doi.org/10.1016/j.compstruc.2023.107174). Rui Pedro Cardoso Coelho, Miguel Vieira de Carvalho, Francisco Manuel Andrade Pires. Computers & Structures 2023.
+- [On the modeling of cavitation and yielding in rubber-toughened amorphous polymers: Fully implicit implementation and optimization-based calibration](https://doi.org/10.1016/j.ijsolstr.2023.112488). Ana Francisca Carvalho Alves, Bernardo P. Ferreira and Francisco Manuel Andrade Pires. International Journal of Solids and Structures 2023.

examples/templates/solvers/abaqus.yaml

@@ -1,9 +1,9 @@
 # Specification for the Abaqus solver
 #
-# In the example below, we register one output fields:
+# In the example below, we register one output field:
 # - 'reaction_x'
 # This is a quantity that is returned from the interface. When using the solver
-# with an objective, use there names to define the prediction fields.
+# with an objective, use their names to define the prediction fields.
 #
 solver:
   #
@@ -21,13 +21,13 @@ solver:
   # for the analysis. You can have multiple cases, each with its own input
   # file and fields.
   cases:
-    # Example for a input file
+    # Example for an input file
     'sample.inp':
       # If the input has only one job this field is optional
       job_name: Job-1 # Job name to extract data
-      # If the input has only one job this field is optional
+      # If the input has only one step this field is optional
       step_name: Step-1 # Step name to extract data
-      # If the input has only one job this field is optional
+      # If the input has only one instance this field is optional
       instance_name: PART-1-1 # Step name to extract data
       fields:
         'reaction_x':

examples/templates/solvers/crate.yaml

@@ -1,9 +1,9 @@
 # Specification for the CRATE solver
 
-# At this moment, the CRATE solver registers one output fields `hresFile`,
+# At this moment, the CRATE solver registers one output field `hresFile`,
 # corresponding to micro homogenised quantities.
 # These are the quantities that are returned from the interface. When using the
-# solver with an objective, use there names to define the prediction fields.
+# solver with an objective, use their names to define the prediction fields.
 
 solver:
   #
@@ -21,7 +21,7 @@ solver:
   # for the analysis. You can have multiple cases, each with its own input
   # file and fields.
   cases:
-    # Example for a input file
+    # Example for an input file
     'input_file.dat':
       fields:
         # Register a 'micro_homogenised_quantity' output field

examples/templates/solvers/curve.yaml

@@ -4,7 +4,7 @@
 # - 'quadratic_curve'
 # - 'exponential_curve'
 # These are the quantities that are returned from the interface. When using the
-# solver with an objective, use there names to define the prediction fields.
+# solver with an objective, use their names to define the prediction fields.
 
 solver:
   #

examples/templates/solvers/links.yaml

@@ -5,7 +5,7 @@
 # - 'macro_stress_strain'
 # - 'micro_homogenised_stress'
 # These are the quantities that are returned from the interface. When using the
-# solver with an objective, use there names to define the prediction fields.
+# solver with an objective, use their names to define the prediction fields.
 
 solver:
   #
@@ -39,7 +39,7 @@ solver:
           field: sigma_xx # Field to extract data (mandatory)
           x_field: F_xx # Optional, by default LoadFactor
           i_elem: 12 # Element number to extract data (mandatory for macro)
-          i_gauss: 2 # Gauss pont number to extract data (mandatory for macro)
+          i_gauss: 2 # Gauss point number to extract data (mandatory for macro)
     # Example for a macroscopic input file
     'micro_input_file.rve':
       fields: