Scihence

Henry's tools for doing science.

Table of Contents

• Scihence
  • Table of Contents
  • Usage
    • Pipelines
  • Development
    • Workflow
    • Setup
  • Unit and integration tests
    • Documentation
    • Acceptance testing
    • Versions
      • Non-release versions
  • TODO

Usage

Installation:

pip install scihence

Importing:

import scihence

Note: PyTorch is not automatically installed since it can be cumbersome depending on which CUDA dependencies are required. You can find out how to install the specific version for you on PyTorch's website.

Pipelines

To explore the outputs of a pipeline:

• In a terminal window, fill in the PATH/TO/DIR_WHERE_PIPELINE_EXECUTED, and run:

  cd PATH/TO/DIR_WHERE_PIPELINE_EXECUTED && mlflow ui
  

• Navigate to your specified experiment (Default if not set), and explore the results.

Development

Workflow

graph TD;
   master(Master branch):::masterclass-->dev
   dev(Dev branch):::devclass-->feature
   feature(Feature branch):::featclass-->changes
   changes(Make changes):::featclass-->document
   document(Document):::featclass-->test
   test(Test):::featclass-->passing
   passing{Passing?}:::featclass
   passing--No-->changes
   passing--Yes-->push
   push(Push):::featclass-->pr
   pr(Pull request):::featclass
   pr--Contributer-->approved
   pr--CI/CD-->approved
   pr--Reviewer-->approved
   approved{Approved?}:::featclass
   approved--No-->changes
   approved--Yes-->merge
   merge(Dev branch):::devclass-->release
   dev-->merge
   release{Release?}:::devclass
   release--No-->feature
   release--Yes-->pr2
   pr2(Pull request):::devclass
   pr2--CI/CD-->approved2
   pr2--Reviewer-->approved2
   approved2{Approved?}:::devclass
   approved2--Yes-->master2
   approved2--No-->dev
   master2(Master branch):::masterclass
   master-->master2

   classDef masterclass fill:#000035, stroke:#000035, color:#c0c0c0;
   classDef devclass fill:#552777, stroke:#552777, color:#aaddff;
   classDef featclass fill:#aaddff, stroke:#aaddff, color:#000035;

   linkStyle 22 fill:none, stroke:#000035,stroke-width:2px;
   linkStyle 0,14,15,18,19 fill:none, stroke:#552777,stroke-width:2px;
   linkStyle 1,2,3,4,5,8,9,10,11 fill:none, stroke:#aaddff,stroke-width:2px;
   linkStyle 7,13,17,20 fill:none, stroke:#c0c0c0,stroke-width:2px;
   linkStyle 6,12,16,21 fill:none, stroke:#ff0000,stroke-width:2px;

Setup

1. Ensure pyenv is installed on your device.

2. Substituting the Python version, run the following code in the terminal at the root of the repository directory:

   make env v=3.a.b && source .venv/bin/activate
   

Unit and integration tests

To run unit and integration tests, run the following code in the terminal at the root of the repository directory:

pytest --junit-xml=docs/source/test-report/local/junit/report.xml
coverage html -d docs/source/test-report/local/coverage
python -m tests.build_junit_report \
    docs/source/test-report/local/junit/report.xml \
    docs/source/test-report/local/junit/report.html

Documentation

The live version of the documentation can be found here.

To build documentation, in your environment run the following code in the terminal at the root of the repository directory:

make docs

You can view the built documentation using:

open docs/build/html/index.html

Note: Documentation building searches for and includes test run artifacts that are produced using scripts similar to the one in Testing. It will still build if not present, but code coverage and the JUnit reports will not be included.

Acceptance testing

In your environment, run the following code in the terminal at the root of the repository directory, replacing and including python versions that are supported:

pyenv shell 3.11.a 3.11.b && tox

Versions

Note: Versioning should only occur for the master branch.

• Before merging, ensure that the version number listed in src/scihence/__init__.py is updated.
• Version numbers are usually given as major.minor.patch. This is how the __version__ variable in __init__.py should be specified when merging from dev into master.
• Having specified the __version__ correctly before merging into master, GitLab CI will take care of packaging and releasing automatically.
• When creating a development version that you would like to upload to the package index, version numbers such as major.minor.patch.devN can be used, for example, 0.1.2.dev0 would be the first development release of version 0.1.2.
• Similarly, alpha, beta, and release candidate releases can be versioned using the semantic notation 0.1.2a0, 0.1.2b0, 0.1.2rc0 respectively (without the 3rd .).

Non-release versions

Non-release versions of scihence that are in a merge request will automatically have a version created with the GitLab CI job ID appended as metadata. For example, a push of 0.1.2.dev12 that builds the package in a job with ID 987654321 would be uploaded to the scihence development package registry as version 0.1.2.dev12+job987654321. This could then be installed locally for testing purposes using

pip install scihence==0.1.2.dev12+job987654321

The extra index URL for this package registry where pip will look should already be configured in the .venv/pip.conf provided your environment was initially created using make env.

TODO

• tox -e py311-wheel does not use wheel
• Test everything
• Document everything
• Save documentation and packages for individual commits
• Generalise to reinforcement learning pipeline
• Ensure accepts GNN inputs