Publish NAS-sourced pretrained MotionNet

LICENSE

@@ -0,0 +1,39 @@
+Academic and Non-Commercial Research Use Software License and Terms of Use
+DeepEthogram: Automated behavior classification (the “Software”, tracked by Harvard Case No. 8336).  The Software was developed by Christopher Harvey and Jim Bohnslav, Department of Neurobiology, Harvard Medical School.
+Using the Software indicates your agreement to be bound by the terms of this Software Use Agreement (“Agreement”). Absent your agreement to the terms below, you (the “End User”) have no rights to hold or use the Software whatsoever.
+President and Fellows of Harvard College (“Harvard”) agrees to grant hereunder the limited non-exclusive license to End User for the use of the Software in the performance of End User’s internal, non-commercial research and academic use at End User’s academic or not-for-profit research institution (“Institution”) on the following terms and conditions:
+    1. NO REDISTRIBUTION. The Software remains the property of Harvard, and End User shall not publish, distribute, or otherwise transfer or make available the Software to any other party.
+
+    2. NO COMMERCIAL USE. End User shall not use the Software for commercial purposes, including for any internal research purposes for or on behalf of any for-profit entity, and any such use of the Software is expressly prohibited.  This prohibition includes, but is not limited to, use of the Software in fee-for-service arrangements, core facilities or laboratories or to provide research services to (or in collaboration with) third parties for a fee, and in industry-sponsored collaborative research projects where any commercial rights are granted to the sponsor.  If End User wishes to use the Software for commercial purposes or for any other restricted purpose, End User must execute a separate license agreement with Harvard.
+
+Requests for use of the Software for or on behalf of for-profit entities or for any commercial purposes, please contact:
+
+Office of Technology Development
+Harvard University
+Smith Campus Center, Suite 727E
+1350 Massachusetts Avenue
+Cambridge, MA 02138 USA
+Telephone: (617) 495-3067
+E-mail: otd@harvard.edu
+
+    3. OWNERSHIP AND COPYRIGHT NOTICE. Harvard owns all intellectual property in the Software. End User shall gain no ownership to the Software. End User shall not remove or delete and shall retain in the Software, in any modifications to Software and in any Derivative Works, the copyright, trademark, or other notices pertaining to Software as provided with the Software.
+
+    4. DERIVATIVE WORKS. End User may create and use Derivative Works, as such term is defined under U.S. copyright laws, provided that any such Derivative Works shall be restricted to non-commercial, internal research and academic use at End User’s Institution.  End User shall not distribute Derivative Works to any third party without the express written consent of Harvard.
+
+    5. FEEDBACK. In order to improve the Software, comments from End Users may be useful. End User agrees to provide Harvard with feedback on the End User’s use of the Software (e.g., any bugs in the Software, the user experience, etc.).  Harvard is permitted to use such information provided by End User in making changes and improvements to the Software without compensation or an accounting to End User.
+
+    6. NON ASSERT. End User acknowledges that Harvard may develop modifications to the Software that may be based on the feedback provided by End User under Section 5 above. Harvard shall not be restricted in any way by End User regarding the use of such information.  End User acknowledges the right of Harvard to prepare, publish, display, reproduce, transmit and or use modifications to the Software that may be substantially similar or functionally equivalent to End User’s modifications and/or improvements if any.  In the event that End User obtains patent protection for any modification or improvement to Software, End User agrees not to allege or enjoin infringement of End User’s patent against Harvard or any of its researchers, medical or research staff, officers, directors and employees.
+
+    7. PUBLICATION & ATTRIBUTION. End User has the right to publish, present, or share results from the use of the Software.  In accordance with customary academic practice, End User will acknowledge Harvard as the provider of the Software and may cite the relevant reference(s) from the following list of publications: N/A
+
+    8. NO WARRANTIES. THE SOFTWARE IS PROVIDED "AS IS." TO THE FULLEST EXTENT PERMITTED BY LAW, HARVARD HEREBY DISCLAIMS ALL WARRANTIES OF ANY KIND (EXPRESS, IMPLIED OR OTHERWISE) REGARDING THE SOFTWARE, INCLUDING BUT NOT LIMITED TO ANY IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OWNERSHIP, AND NON-INFRINGEMENT.  HARVARD MAKES NO WARRANTY ABOUT THE ACCURACY, RELIABILITY, COMPLETENESS, TIMELINESS, SUFFICIENCY OR QUALITY OF THE SOFTWARE.  HARVARD DOES NOT WARRANT THAT THE SOFTWARE WILL OPERATE WITHOUT ERROR OR INTERRUPTION.
+
+    9. Limitations of Liability and Remedies. USE OF THE SOFTWARE IS AT END USER’S OWN RISK. IF END USER IS DISSATISFIED WITH THE SOFTWARE, ITS EXCLUSIVE REMEDY IS TO STOP USING IT.  IN NO EVENT SHALL HARVARD BE LIABLE TO END USER OR ITS INSTITUTION, IN CONTRACT, TORT OR OTHERWISE, FOR ANY DIRECT, INDIRECT, SPECIAL, INCIDENTAL, CONSEQUENTIAL, PUNITIVE OR OTHER DAMAGES OF ANY KIND WHATSOEVER ARISING OUT OF OR IN CONNECTION WITH THE SOFTWARE, EVEN IF HARVARD IS NEGLIGENT OR OTHERWISE AT FAULT, AND REGARDLESS OF WHETHER HARVARD IS ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.
+
+    10. INDEMNIFICATION. To the extent permitted by law, End User shall indemnify, defend and hold harmless Harvard and its current or future directors, trustees, officers, faculty, medical and professional staff, employees, students and agents and their respective successors, heirs and assigns (the "Indemnitees"), against any liability, damage, loss or expense (including reasonable attorney's fees and expenses of litigation) incurred by or imposed upon the Indemnitees or any one of them in connection with any claims, suits, actions, demands or judgments arising from End User’s breach of this Agreement or its Institution’s use of the Software except to the extent caused by the gross negligence or willful misconduct of Harvard. This indemnification provision shall survive expiration or termination of this Agreement.
+
+    11. GOVERNING LAW. This Agreement shall be construed and governed by the laws of the Commonwealth of Massachusetts regardless of otherwise applicable choice of law standards.
+
+    12. NON-USE OF NAME.  Nothing in this License and Terms of Use shall be construed as granting End Users or their Institutions any rights or licenses to use any trademarks, service marks or logos associated with the Software.  You may not use the terms “Harvard” (or a substantially similar term) in any way that is inconsistent with the permitted uses described herein. You agree not to use any name or emblem of Harvard or any of its subdivisions for any purpose, or to falsely suggest any relationship between End User (or its Institution) and Harvard, or in any manner that would infringe or violate any of Harvard’s rights.
+
+    13. End User represents and warrants that it has the legal authority to enter into this License and Terms of Use on behalf of itself and its Institution.

README.md

@@ -0,0 +1,104 @@
+---
+model_name: DeepEthogram MotionNet
+language: en
+license: other
+license_name: deepethogram-academic-noncommercial
+license_link: LICENSE
+library_name: deepethogram
+tags:
+- deepethogram
+- pytorch
+- optical-flow
+- motionnet
+- motionnet
+- kinetics700
+- animal-behavior
+- pretrained
+---
+
+# DeepEthogram MotionNet
+
+MotionNet is a optical-flow generator pretrained on Kinetics700 videos for [DeepEthogram](https://github.com/jbohnslav/deepethogram).
+This repository contains this model's checkpoint and historical training hyperparameters.
+See the [DeepEthogram collection](https://huggingface.co/collections/jbohnslav/deepethogram-pretrained-models-6ad61e8af1ac368c56d8deec) for the other models.
+
+## Model details
+
+| Property | Value |
+| --- | --- |
+| Architecture | MotionNet |
+| Task | optical-flow |
+| Input | 11 RGB frames stacked as `(N, 33, H, W)` |
+| Output | a three-scale optical-flow pyramid; highest-resolution shape `(1, 20, 32, 32)` for the example |
+| Pretraining data | Kinetics700, as recorded in the historical hyperparameters |
+| Source run | `200310_174416_MotionNet_kinetics` |
+| Framework | PyTorch; DeepEthogram |
+
+The model predicts motion fields from video frames. It does not classify behaviors.
+Hugging Face has no dedicated optical-flow pipeline category in its current task registry;
+this repo uses the explicit `optical-flow` tag and DeepEthogram library metadata.
+
+## Download and load
+
+Install DeepEthogram and the [Hugging Face CLI](https://huggingface.co/docs/huggingface_hub/guides/cli).
+Download only this model into an existing DeepEthogram project's pretrained directory:
+
+```bash
+hf download jbohnslav/deepethogram-motionnet --revision nas-2026-10-19 --local-dir /path/to/project/models/pretrained_models/200310_174416_MotionNet_kinetics
+```
+
+From that run directory, verify the artifacts with `shasum -a 256 -c SHA256SUMS`.
+The `checkpoint.pt` and `hyperparameters.yaml` at its root let DeepEthogram discover
+this model using its existing project layout.
+
+To load directly in Python, set `run_dir` to the directory downloaded above:
+
+```python
+from pathlib import Path
+import torch
+from deepethogram import utils
+
+from deepethogram.flow_generator.models.MotionNet import MotionNet
+model = MotionNet()
+run_dir = Path('/path/to/project/models/pretrained_models/200310_174416_MotionNet_kinetics')
+state_dict, _, _ = utils.load_state_dict_from_file(run_dir / 'checkpoint.pt')
+model.load_state_dict(state_dict, strict=True)
+model.eval()
+with torch.inference_mode():
+    output = model(torch.zeros(1, 33, 64, 64))
+```
+
+The zero-valued example checks shapes and loading. For real videos use DeepEthogram's
+video preprocessing and normalization. Historical settings are in `hyperparameters.yaml`;
+`model_config.json` summarizes architecture and input/output conventions.
+
+## Intended use and limitations
+
+Historical YAML files contain old filesystem paths and legacy serialization tags; they are
+provenance records, not portable project configs. Checkpoints retain their original PyTorch
+serialization. Use DeepEthogram, rather than Transformers `AutoModel`, to load them.
+
+This release contains initialization weights, not a complete trained behavior inference run:
+newer inference helpers expect `config.yaml` and associated metrics from your fine-tuned run.
+The complete historical plots, metrics, and additional stream snapshots remain in the
+[legacy archive](https://huggingface.co/jbohnslav/deepethogram-pretrained).
+
+## Validation and provenance
+
+The checkpoint and hyperparameters were copied without conversion from the author's NAS
+pretrained directory for `niv_revision_deepethogram`. Their SHA-256 checksums match the
+verified legacy archive; `SHA256SUMS` also covers this repo's license and model configuration.
+Validated with PyTorch 2.4.1 and DeepEthogram source revision
+`1541eec6958f90673b79c402e10b434c8cb7c868`: strict parameter loading and finite CPU
+outputs on the synthetic input above. This is a compatibility check, not an accuracy benchmark.
+
+## License and citation
+
+[LICENSE](LICENSE) reproduces the original DeepEthogram Harvard Academic and Non-Commercial
+Research Use Software License and Terms of Use unchanged. It restricts commercial use and
+end-user redistribution. This mirror grants no additional permissions and does not relicense
+the assets; commercial inquiries should go to Harvard OTD as described in the license.
+
+Bohnslav et al. (2021). *DeepEthogram, a machine learning pipeline for supervised behavior
+classification from raw pixels*. eLife 10:e63377.
+[doi:10.7554/eLife.63377](https://doi.org/10.7554/eLife.63377).

SHA256SUMS

@@ -0,0 +1,4 @@
+899e15e791552500b93f3ddcc239f570670edd9d9016c05b482ba04cb87415b0  LICENSE
+c75e175724ae04a94fc622cfe8949e63656a60639556b65f8d640eb2944a511a  checkpoint.pt
+fc8f58e37e37dccc2f6bddb0ad8ce1b39b0d448d78048adedf8a60b32f6668eb  hyperparameters.yaml
+2cd6a01c655785a101d2efcf54f90f456dd8e2127553e6e249a0e69d256526d2  model_config.json

checkpoint.pt

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:c75e175724ae04a94fc622cfe8949e63656a60639556b65f8d640eb2944a511a
+size 183604611

hyperparameters.yaml

@@ -0,0 +1,94 @@
+LR: 0.5
+UD: 0.0
+batch_size: 16
+brightness: 0.25
+classifier: resnet18
+config_file: null
+contrast: 0.1
+crop_size: !!python/tuple
+- 256
+- 256
+dali: true
+data_dir: /media/jim/FASTER/kinetics700
+dataset: kinetics
+degrees: 10
+distributed: false
+early_stopping_begins: null
+final_activation: softmax
+flow_generator: MotionNet
+flow_loss: MotionNet
+flow_max: 5
+fp16: false
+gpu_id: 1
+input_images: 11
+inputs: rgb
+lr: 0.0001
+milestones:
+- 50
+- 100
+- 150
+- 200
+- 250
+- 300
+min_lr: 5.0e-07
+model: flow_generator
+model_dir: models
+name: kinetics
+normalization:
+  flow:
+    N: 2097152000000
+    mean: null
+    std: null
+  rgb:
+    N: 209715200000
+    mean:
+    - 0.4345759153366089
+    - 0.39914101362228394
+    - 0.37257176637649536
+    std:
+    - 0.2809292674064636
+    - 0.27423909306526184
+    - 0.27391594648361206
+notes: dali_only_3_resolutions
+num_epochs: 1000
+num_flows: null
+num_rgb: 11
+num_workers: 8
+pad: null
+patience: 10
+preset: null
+project_dir: null
+random_resize: false
+reduction_factor: !!python/object/apply:numpy.core.multiarray.scalar
+- !!python/object/apply:numpy.dtype
+  args:
+  - f8
+  - 0
+  - 1
+  state: !!python/tuple
+  - 3
+  - <
+  - null
+  - null
+  - null
+  - -1
+  - -1
+  - 0
+- !!binary |
+  D0lIYhM91D8=
+reload_split: true
+resize: null
+scheduler: plateau
+should_overwrite_args: false
+should_viz: true
+splitfile: null
+steps_per_epoch: 1000
+steps_per_test_epoch: 20
+steps_per_validation_epoch: 1000
+stopping_type: plateau
+train_val_test_split:
+- 0.8
+- 0.2
+- 0.0
+weight_loss: true
+weights: null

model_config.json

@@ -0,0 +1,19 @@
+{
+  "format_version": 1,
+  "library_name": "deepethogram",
+  "model_name": "MotionNet",
+  "architecture": "MotionNet",
+  "task": "optical-flow",
+  "source_run": "200310_174416_MotionNet_kinetics",
+  "checkpoint": "checkpoint.pt",
+  "flow_generator": "MotionNet",
+  "num_rgb_frames": 11,
+  "input_shape": [
+    "N",
+    33,
+    "H",
+    "W"
+  ],
+  "num_classes": null,
+  "deepethogram_source_revision": "1541eec6958f90673b79c402e10b434c8cb7c868"
+}