Copyright info, sphinx documentation, readme

CHANGELOG.md

@@ -0,0 +1,4 @@
+Version 0.1.0, released on May 1, 2024
+--------------------------------------
+
+- Initial release under GPL-2.

CONTRIBUTING.md

@@ -0,0 +1,199 @@
+[![CI](https://github.com/hippylib/hippylibx/actions/workflows/CI_testing.yml/badge.svg)](https://github.com/hippylib/hippylibx/actions/workflows/CI_testing.yml)
+
+```
+                                        Inverse Problem Python library
+```
+```
+ __        ______  _______   _______   __      __  __  __  __     ______       _____  
+/  |      /      |/       \ /       \ /  \    /  |/  |/  |/  |    \    \      /    /     
+$$ |____  $$$$$$/ $$$$$$$  |$$$$$$$  |$$  \  /$$/ $$ |$$/ $$ |____ \ $$ \    / $$ /   
+$$      \   $$ |  $$ |__$$ |$$ |__$$ | $$  \/$$/  $$ |/  |$$      \ \ $$ \  / $$ /    
+$$$$$$$  |  $$ |  $$    $$/ $$    $$/   $$  $$/   $$ |$$ |$$$$$$$  | | $$$$$$$$ /     
+$$ |  $$ |  $$ |  $$$$$$$/  $$$$$$$/     $$$$/    $$ |$$ |$$ |  $$ | | $$$$$$$$ |     
+$$ |  $$ | _$$ |_ $$ |      $$ |          $$ |    $$ |$$ |$$ |__$$ |/ $$ /  \ $$ \    
+$$ |  $$ |/ $$   |$$ |      $$ |          $$ |    $$ |$$ |$$    $$/  $$ /    \ $$ \   
+$$/   $$/ $$$$$$/ $$/       $$/           $$/     $$/ $$/ $$$$$$$/_ $$_/      \_$$_\  
+
+```
+```
+                                        https://hippylib.github.io
+```
+### How to Contribute
+
+The `hIPPYlibX` team welcomes contributions at all levels: bugfixes, code improvements, new capabilities, improved documentation, or new examples/tutorials.
+
+Use a pull request (PR) toward the `hippylibx:main` branch to propose your contribution. If you are planning significant code changes, or have any questions, you should also open an [issue](https://github.com/hippylib/hippylibx/issues) before issuing a PR.
+
+See the [Quick Summary](#quick-summary) section for the main highlights of our GitHub workflow. For more details, consult the following sections and refer back to them before issuing pull requests:
+
+- [GitHub Workflow](#github-workflow)
+    - [hIPPYlib Organization](#hippylib-organization)
+    - [New Feature Development](#new-feature-development)
+    - [Developer Guidelines](#developer-guidelines)
+    - [Pull Requests](#pull-requests)
+    - [Pull Request Checklist](#pull-request-checklist)
+    - [Automated Testing](#automated-testing)
+- [Contact Information](#contact-information)
+
+Contributing to hIPPYlib requires knowledge of Git and, likely, inverse problems. If you are new to Git, see the [GitHub learning resources](https://docs.github.com/en/get-started/start-your-journey/git-and-github-learning-resources). To learn more about inverse problems, see our [tutorial page](https://hippylib.github.io/).
+
+By submitting a pull request, you are affirming the [Developer's Certificate of Origin](#developers-certificate-of-origin-11) at the end of this file.
+### Quick Summary
+
+- We encourage you to [join the hIPPYlib organization](#hippylib-organization) and create development branches off `hippylibx:main`.
+- Please follow the [developer guidelines](#developer-guidelines), in particular with regards to documentation and code styling.
+- Pull requests should be issued toward `hippylibx:main`. Make sure to check the items off the [Pull Request Checklist](#pull-request-checklist).
+- After approval, hIPPYlib developers merge the PR in `hippylibx:main`.
+- Don't hesitate to [contact us](#contact-information) if you have any questions.
+
+### GitHub Workflow
+
+The GitHub organization, [https://github.com/hippylib](https://github.com/hippylib), is the main developer hub for the hIPPYlib project.
+
+If you plan to make contributions or will like to stay up-to-date with changes in the code, we *strongly encourage you* to *[join the hIPPYlib organization](hippylib-organization).*
+
+This will simplify the workflow (by providing you additional permissions), and will allow us to reach you directly with project announcements.
+### hIPPYlib Organization
+
+- Before you can start, you need a GitHub account, here are a few suggestions:
+    - Create the account at: github.com/join.
+    - For easy identification, please add your name and maybe a picture of you at: [https://github.com/settings/profile](https://github.com/settings/profile).
+    - To receive notification, set a primary email at: [https://github.com/settings/emails](https://github.com/settings/emails).
+    - For password-less pull/push over SSH, add your SSH keys at: [https://github.com/settings/keys](https://github.com/settings/keys).
+
+- [Contact us](#contact-information) for an invitation to join the hIPPYlib GitHub organization.
+
+- You should receive an invitation email, which you can directly accept. Alternatively, *after logging into GitHub*, you can accept the invitation at the top of [https://github.com/hippylib](https://github.com/hippylib).
+
+- Consider making your membership public by going to [https://github.com/orgs/hippylib/people](https://github.com/orgs/hippylib/people) and clicking on the organization visibility dropbox next to your name.
+
+- Project discussions and announcements will be posted at [https://github.com/orgs/hippylib/teams/everyone](https://github.com/orgs/hippylib/teams/everyone).
+
+- The hIPPYlibX source code is in the [hippylibX](https://github.com/hippylib/hippylibx) repository.
+
+### New Feature Development
+
+- A new feature should be important enough that at least one person, the proposer, is willing to work on it and be its champion.
+
+- The proposer creates a branch for the new feature (with suffix `-dev`), off the `main` branch, or another existing feature branch, for example:
+
+```
+# Clone assuming you have setup your ssh keys on GitHub:
+git clone [email protected]:hippylib/hippylibx.git
+
+# Alternatively, clone using the "https" protocol:
+git clone https://github.com/hippylib/hippylibx.git
+
+# Create a new feature branch starting from "main":
+git checkout main
+git pull
+git checkout -b feature-dev
+
+# Work on "feature-dev", add local commits
+# ...
+
+# (One time only) push the branch to github and setup your local
+# branch to track the github branch (for "git pull"):
+git push -u origin feature-dev
+````
+- **We prefer that you create the new feature branch as a fork.** To allow hIPPYlib developers to edit the PR, please [enable upstream edits](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/working-with-forks/allowing-changes-to-a-pull-request-branch-created-from-a-fork).
+
+- The typical feature branch name is `new-feature-dev`, e.g. `optimal_exp_design-dev`. While not frequent in hIPPYlibX, other suffixes are possible, e.g. `-fix`, `-doc`, etc.
+
+### Developer Guidelines
+
+- Keep the code lean and as simple as possible
+    - Well-designed simple code is frequently more general and powerful.
+    - Lean code base is easier to understand by new collaborators.
+    - New features should be added only if they are necessary or generally useful.
+    - Code must be compatible with Python 3.
+    - When adding new features add an example in the `example` folder.
+    - The preferred way to export solutions for visualization in paraview is using `dl.XDMFFile`
+
+- Keep the code general and reasonably efficient
+    - Main goal is fast prototyping for research.
+    - When in doubt, generality wins over efficiency.
+    - Respect the needs of different users (current and/or future).
+
+- Keep things separate and logically organized
+    - General usage features go in hIPPYlibX (implemented in as much generality as possible), non-general features go into external apps/projects.
+    - Inside hIPPYlibX, compartmentalize between modeling, algorithms, utils, etc.
+    - Contributions that are project-specific or have external dependencies are allowed (if they are of broader interest), but should be `#ifdef`-ed and not change the code by default.
+
+- Code specifics
+    - All significant new classes, methods and functions have sphinx-style documentation in source comments.
+    - Code styling should resemble existing code.
+    - When manually resolving conflicts during a merge, make sure to mention the conflicted files in the commit message.
+
+### Pull Requests
+- When your branch is ready for other developers to review / comment on the code, create a pull request towards `hippylibx:main`.
+
+- Pull request typically have titles like:
+
+    `Description [new-feature-dev]`
+
+    for example:
+
+    `Bayesian Optimal Design of Experiments [oed-dev]`
+
+    Note the branch name suffix (in square brackets).
+
+- Titles may contain a prefix in square brackets to emphasize the type of PR. Common choices are: `[DON'T MERGE]`, `[WIP]` and `[DISCUSS]`, for example:
+
+    `[DISCUSS] Bayesian Optimal Design of Experiments [oed-dev]`
+
+- Add a description, appropriate labels and assign yourself to the PR. The hIPPYlib team will add reviewers as appropriate.
+
+- List outstanding TODO items in the description.
+
+- Track the Github Actions [continuous integration](#automated-testing) builds at the end of the PR. These should run clean, so address any errors as soon as possible.
+
+### Pull Request Checklist
+
+Before a PR can be merged, it should satisfy the following:
+
+- [ ] CI runs without errors.
+
+- [ ] Update `CHANGELOG`:
+    - [ ] Is this a new feature users need to be aware of? New or updated application or tutorial?
+    - [ ] Does it make sense to create a new section in the CHANGELOG to group with other related features?
+- [ ] New examples/applications/tutorials:
+    - [ ] All new examples/applications/tutorials run as expected.
+    - [ ] Add a fast version of the example/application/tutorial to Github Actions CI
+- [ ] New capability:
+    - [ ] All significant new classes, methods and functions have sphinx-style documentation in source comments.
+    - [ ] Add new examples/applications/tutorials to highlight the new capability.
+    - [ ] For new classes, functions, or modules, edit the corresponding .rst file in the doc folder.
+    - [ ] If this is a major new feature, consider mentioning in the short summary inside README (rare).
+    - [ ] If this is a C++ extension, the package_data dictionary in setup.py should include new files.
+
+### Automated Testing
+
+We use Github Actions CI to drive the default tests on the main and feature branches. See the `.yml` file at [CI_testing.yml](https://github.com/hippylib/hippylibx/blob/main/.github/workflows/CI_testing.yml) 
+
+- Tests on the `main` branch are triggered whenever a push is issued on this branch.
+
+### Contact Information
+
+- Contact the hIPPYlib team by posting to the [GitHub issue tracker](https://github.com/hippylib/hippylibx/issues). Please perform a search to make sure your question has not been answered already.
+
+### Slack channel
+
+The hIPPYlib slack channel is a good resource to request and receive help with using hIPPYlib. Everyone is invited to read and take part in discussions. Discussions about development of new features in hIPPYlib also take place here. You can join our Slack community by filling in [this form](https://docs.google.com/forms/d/e/1FAIpQLSf4eg3dtOwk1dCqKY9_R21beOJVvy6ECuSB2d1FltVXNwXqMw/viewform).
+
+### [Developer's Certificate of Origin 1.1](https://developercertificate.org/)
+
+By making a contribution to this project, I certify that:
+
+(a) The contribution was created in whole or in part by me and I have the right to submit it under the open source license indicated in the file; 
+
+or
+
+(b) The contribution is based upon previous work that, to the best of my knowledge, is covered under an appropriate open source license and I have the right under that license to submit that work with modifications, whether created in whole or in part by me, under the same open source license (unless I am permitted to submit under a different license), as indicated in the file; or
+
+(c) The contribution was provided directly to me by some other person who certified (a), (b) or (c) and I have not modified it.
+
+(d) I understand and agree that this project and the contribution are public and that a record of the contribution (including all personal information I submit with it, including my sign-off) is maintained indefinitely and may be redistributed consistent with this project or the open source license(s) involved.
+
+---
+> *Acknowledgement*: We thank the [MFEM team](https://github.com/mfem) for allowing us to use their contributing guidelines file as template.

COPYRIGHT

@@ -0,0 +1,38 @@
+# --------------------------------------------------------------------------bc-
+# Copyright (C) 2024 The University of Texas at Austin
+#
+# This file is part of the hIPPYlibx library. For more information and source
+# code availability see https://hippylib.github.io.
+#
+# SPDX-License-Identifier: GPL-2.0-only
+# --------------------------------------------------------------------------ec-
+
+COPYRIGHT
+
+The following copyright applies to each file in the hIPPYlibx
+distribution, unless otherwise stated in the file:
+
+Copyright (c) 2024, The University of Texas at Austin.
+
+LICENSE
+
+hIPPYlibx is a free software; you can redistribute it and/or modify it
+under the terms of the GNU General Public License (as published by the
+Free Software Foundation) version 2.0 dated June 1991.
+
+hIPPYlibx is distributed in the hope that it will be useful, but
+WITHOUT ANY WARRANTY; without even the IMPLIED WARRANTY OF
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the terms
+and conditions of the GNU Lesser General Public License for more
+details.
+
+You should have received a copy of the GNU General Public
+License along with this library (file LICENSE); if not, write to the
+Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
+Boston, MA 02110-1301 USA.
+
+Please see
+
+            https://hippylib.github.io
+
+for more information and source code availability.

Dockerfile

@@ -3,6 +3,8 @@ MAINTAINER Venugopal Ranganathan <[email protected]>
 RUN pip install memory_profiler
 RUN pip install psutil
 RUN pip install pylint
+RUN pip install m2r
+RUN pip install sphinx_mdinclude
 
 RUN wget -O paraview.tar.gz "https://www.paraview.org/paraview-downloads/download.php?submit=Download&version=v5.12&type=binary&os=Linux&downloadFile=ParaView-5.12.0-MPI-Linux-Python3.10-x86_64.tar.gz"
 RUN tar xzf paraview.tar.gz && mv ParaView-5.12.0-MPI-Linux-Python3.10-x86_64 ParaView_5.1.2

INSTALL.md

@@ -0,0 +1,50 @@
+```
+                                        Inverse Problem Python library
+```
+```
+         __        ______  _______   _______   __      __  __  __  __     ______       _____  
+        /  |      /      |/       \ /       \ /  \    /  |/  |/  |/  |    \    \      /    /     
+        $$ |____  $$$$$$/ $$$$$$$  |$$$$$$$  |$$  \  /$$/ $$ |$$/ $$ |____ \ $$ \    / $$ /   
+        $$      \   $$ |  $$ |__$$ |$$ |__$$ | $$  \/$$/  $$ |/  |$$      \ \ $$ \  / $$ /    
+        $$$$$$$  |  $$ |  $$    $$/ $$    $$/   $$  $$/   $$ |$$ |$$$$$$$  | | $$$$$$$$ /     
+        $$ |  $$ |  $$ |  $$$$$$$/  $$$$$$$/     $$$$/    $$ |$$ |$$ |  $$ | | $$$$$$$$ |     
+        $$ |  $$ | _$$ |_ $$ |      $$ |          $$ |    $$ |$$ |$$ |__$$ |/ $$ /  \ $$ \    
+        $$ |  $$ |/ $$   |$$ |      $$ |          $$ |    $$ |$$ |$$    $$/  $$ /    \ $$ \   
+        $$/   $$/ $$$$$$/ $$/       $$/           $$/     $$/ $$/ $$$$$$$/_ $$_/      \_$$_\  
+
+```
+```
+                                        https://hippylib.github.io
+```
+
+`hIPPYlibX` depends on [FEniCSx](https://fenicsproject.org/) version 0.8.0 released in April 2024.
+
+`FEniCSx` needs to be built with the following dependencies enabled:
+* `numpy`, `scipy`, `matplotlib`, `mpi4py`
+* `petsc4py` (version 3.21.0 or above)
+* `slepc4py` (version 3.21.0 or above)
+
+# FEniCSx installation
+All the  methods to install `FEniCSx` are given on the FEniCSx [installation](https://github.com/FEniCS/dolfinx#installation) page.
+We recommend using their prebuilt `Docker` images.
+## Run FEniCSx from Docker (Linux, MacOS, Windows)
+First you will need to install [Docker](https://www.docker.com/) on your system. MacOS and Windows users should preferably use Docker for Mac or Docker for Windows --- if it is compatible with their system --- instead of the legacy version Docker Toolbox.
+
+For `FEniCSx` version 0.8.0, the Docker image is pulled using 
+```
+docker pull dolfinx/dolfinx:v0.8.0
+```
+The above command can be specified in a [`Dockerfile`](https://github.com/hippylib/hippylibx/blob/main/Dockerfile) as in the `hIPPYlibX` directory.
+
+Once the `Dockerfile` is built, it can be run using the `docker run` command. The present working directory can be shared when running the Docker image which allows for ease in navigating the `hIPPYlibX` directory inside the Docker container.
+
+For instance, the Docker image can be built and run using the following commands:
+```
+docker build -t hIPPYlibX_image:v1 .
+```
+
+```
+docker run -it -v $(pwd):/home hIPPYlibX_image:v1
+```
+### Other ways to build FEniCSx
+For instructions on other ways to build `FEniCSx`, we refer to the FEniCSx project [download page](https://github.com/FEniCS/dolfinx#installation). Note that this instructions always refer to the latest version of FEniCSx which may or may not be yet supported by hIPPYlibX. Always check the hIPPYlibX website for supported FEniCSx versions.