# ThreeDWorld (TDW)

**ThreeDWorld (TDW)** is a platform for interactive multi-modal physical simulation. With TDW, users can simulate high-fidelity sensory data and physical interactions between mobile agents and objects in a wide variety of rich 3D environments.

TDW was developed primarily by Jeremy Schwartz and [Esther Alter](https://github.com/alters-mit). It is now maintained by Esther Alter.

**TDW is now in [long-term support (LTS)](https://github.com/threedworld-mit/tdw/pull/709). TDW will receive only minor updates and bug fixes.**

![](splash.jpg)

- [Code of Conduct](https://github.com/threedworld-mit/tdw/blob/master/code_of_conduct.md)
- [Changelog](https://github.com/threedworld-mit/tdw/blob/master/Documentation/Changelog.md)
- [License](https://github.com/threedworld-mit/tdw/blob/master/LICENSE.txt)
- [Website](https://threedworld.org/)
- [Example controllers](https://github.com/threedworld-mit/tdw/tree/master/Python/example_controllers)

# General guide to TDW

## Setup

### 1.1 Installation (Read this first!)

1. [Install TDW](Documentation/lessons/setup/install.md)
   - [On a personal computer (Linux, MacOS, Windows)](Documentation/lessons/setup/pc.md)
   - [On a server](Documentation/lessons/setup/server.md)
   - [On a personal computer + a server](Documentation/lessons/setup/pc_server.md)
2. [Upgrade TDW](Documentation/lessons/setup/upgrade.md)

### 1.2 How to run TDW on a Linux server

1. [Overview](Documentation/lessons/remote/overview.md)
2. [Launch a TDW build on a remote server from a personal computer](Documentation/lessons/remote/launch_build.md)
3. [Remote rendering with xpra](Documentation/lessons/remote/xpra.md)
4. [X11 forwarding](Documentation/lessons/remote/x11_forwarding.md)

## Core Concepts

1. [The controller](Documentation/lessons/core_concepts/controller.md)
2. [Auto-launching the TDW build](Documentation/lessons/core_concepts/launch_build.md)
3. [Commands](Documentation/lessons/core_concepts/commands.md)
4. [Design philosophy of TDW](Documentation/lessons/core_concepts/design_philosophy.md)
5. [Scenes](Documentation/lessons/core_concepts/scenes.md)
6. [Avatars and cameras](Documentation/lessons/core_concepts/avatars.md)
7. [Add-ons and the `ThirdPersonCamera`](Documentation/lessons/core_concepts/add_ons.md)
8. [Objects](Documentation/lessons/core_concepts/objects.md)
9. [Output data](Documentation/lessons/core_concepts/output_data.md)
10. [Images](Documentation/lessons/core_concepts/images.md)
11. [Outdoor scenes](Documentation/lessons/core_concepts/outdoor_scenes.md)

## Troubleshooting

1. [How to report an issue](Documentation/lessons/troubleshooting/issues.md)
2. [Common errors](Documentation/lessons/troubleshooting/common_errors.md)
3. [Performance optimizations](Documentation/lessons/troubleshooting/performance_optimizations.md)
4. [Good coding practices](Documentation/lessons/troubleshooting/good_coding_practices.md)

# Tutorials

## 1. Scene Setup

**[Overview](Documentation/lessons/scene_setup/overview.md)**

### 1.1 Scene Setup (High-Level APIs)

1. [Overview](Documentation/lessons/scene_setup_high_level/overview.md)
2. [Procedural generation (the `ProcGenKitchen` add-on)](Documentation/lessons/scene_setup_high_level/proc_gen_kitchen.md)
2. [Regions, interior regions, and rooms](Documentation/lessons/scene_setup_high_level/rooms.md)
3. [Procedural object arrangements](Documentation/lessons/scene_setup_high_level/arrangements.md)
4. [Scripted object placement (floorplan layouts)](Documentation/lessons/scene_setup_high_level/floorplans.md)
5. [Reset a scene](Documentation/lessons/scene_setup_high_level/reset_scene.md)

High-level APs: [Floorplan](Documentation/python/add_ons/floorplan.md) and [ProcGenKitchen](Documentation/python/add_ons/proc_gen_kitchen.md)

### 1.2 Scene Setup (Low-Level APIs)

1. [Overview](Documentation/lessons/scene_setup_low_level/overview.md)
2. [Units and data formats](Documentation/lessons/scene_setup_low_level/units.md)
3. [`Bounds` output data](Documentation/lessons/scene_setup_low_level/bounds.md)
4. [Visual materials, textures, and colors](Documentation/lessons/scene_setup_low_level/materials_textures_colors.md)
5. [ProcGenRoom](Documentation/lessons/scene_setup_low_level/proc_gen_room.md)

## 2. 3D Models

### 2.1 Other model libraries

1. [Overview](Documentation/lessons/3d_models/overview.md)
2. [Free models](Documentation/lessons/3d_models/free_models.md)
3. [Non-free models](Documentation/lessons/3d_models/non_free_models.md)

### 2.2 Custom models

1. [Add your own models to TDW](Documentation/lessons/custom_models/custom_models.md)
2. [Add ShapeNet models to TDW](Documentation/lessons/custom_models/shapenet.md)

### 2.3 Composite (articulated) objects

1. [Overview](Documentation/lessons/composite_objects/overview.md)
2. [Composite objects in TDW](Documentation/lessons/composite_objects/composite_objects.md)
3. [Create a composite object from a prefab](Documentation/lessons/composite_objects/create_from_prefab.md)
4. [Create a composite object from a .urdf file](Documentation/lessons/composite_objects/create_from_urdf.md)

## 3. Read/Write to Disk

1. [Overview](Documentation/lessons/read_write/overview.md)
2. [The `Logger` and `LogPlayback` add-ons](Documentation/lessons/read_write/logger.md)
3. [The `JsonWriter` add-on](Documentation/lessons/read_write/json.md)
4. [The `OutputDataWriter` add-on](Documentation/lessons/read_write/output_data_writer.md)
5. [Create a custom data writer](Documentation/lessons/read_write/custom_writers.md)
6. [Import .sdf and .lisdf files](Documentation/lessons/read_write/lisdf.md)
7. [Images](Documentation/lessons/core_concepts/images.md) (Cross-referenced with "Core Concepts")
8. [Audio](Documentation/lessons/audio/overview.md) (Cross-referenced with "Audio")
9. [Video](Documentation/lessons/video/overview.md) (Cross-referenced with "Video Recording")

## 4. Semantic States

1. [Overview](Documentation/lessons/semantic_states/overview.md)
2. [Line of sight (`Raycast` output data)](Documentation/lessons/semantic_states/raycast.md)
3. [Proximity to region (`Overlap` output data)](Documentation/lessons/semantic_states/overlap.md)
3. [Proximity to other objects (the `TriggerCollisionManager` add-on)](Documentation/lessons/semantic_states/trigger_collisions.md)
3. [Containment (the `ContainerManager` add-on)](Documentation/lessons/semantic_states/containment.md)
4. [Open and closed states](Documentation/lessons/semantic_states/openness.md)
4. [Grasped objects](Documentation/lessons/semantic_states/grasped.md)

## 5. Visual Perception

1. [Overview](Documentation/lessons/visual_perception/overview.md)
2. [Instance ID segmentation colors (`_id` pass)](Documentation/lessons/visual_perception/id.md)
3. [Semantic category segmentation colors (`_category` pass)](Documentation/lessons/visual_perception/category.md)
4. [Depth maps (`_depth` and `_depth_simple` passes)](Documentation/lessons/visual_perception/depth.md)
5. [Motion perception (`_flow` pass)](Documentation/lessons/visual_perception/flow.md)
6. [Other image passes (`_mask`, `_normals`, and `_albedo` passes)](Documentation/lessons/visual_perception/other_passes.md)
7. [`Occlusion` output data](Documentation/lessons/visual_perception/occlusion.md)

## 6. Camera Controls

1. [Overview](Documentation/lessons/camera/overview.md)
2. [Move a camera](Documentation/lessons/camera/position.md)
3. [Rotate a camera](Documentation/lessons/camera/rotation.md)
4. [Follow an object](Documentation/lessons/camera/follow.md)
4. [The `CinematicCamera` add-on](Documentation/lessons/camera/cinematic_camera.md)

## 7. Photorealism

1. [Overview](Documentation/lessons/photorealism/overview.md)
2. [Lighting (HDRI skyboxes)](Documentation/lessons/photorealism/lighting.md)
3. [Post-processing](Documentation/lessons/photorealism/post_processing.md)
4. [Interior lighting (the `InteriorSceneLighting` add-on)](Documentation/lessons/photorealism/interior_lighting.md)
5. [Depth of field](Documentation/lessons/photorealism/depth_of_field.md)
6. [V-Ray Rendering](Documentation/lessons/photorealism/vray.md)

High-level API: [tdw_image_dataset](https://github.com/alters-mit/tdw_image_dataset)

## 8. Physics

**[Overview](Documentation/lessons/physx/overview.md)**

### 8.1 Physics (PhysX)

1. [PhysX](Documentation/lessons/physx/physx.md)
2. [Object physics parameters](Documentation/lessons/physx/physics_objects.md)
3. [`Rigidbodies` output data](Documentation/lessons/physx/rigidbodies.md)
4. [`Collision` output data](Documentation/lessons/physx/collisions.md)
5. [Apply forces to objects](Documentation/lessons/physx/forces.md)
6. [Skip physics frames](Documentation/lessons/physx/step_physics.md)
7. [Disable physics](Documentation/lessons/physx/disable_physics.md)

High-level API: [tdw_physics](https://github.com/alters-mit/tdw_physics)

### 8.2 Physics (Obi)

1. [Obi](Documentation/lessons/obi/obi.md)
2. [Fluids](Documentation/lessons/obi/fluids.md)
3. [Wind](Documentation/lessons/obi/wind.md)
4. [Cloth](Documentation/lessons/obi/cloth.md)
5. [`ObiParticles` output data](Documentation/lessons/obi/obi_particles.md)
6. [Colliders and collision materials](Documentation/lessons/obi/colliders_and_collision_materials.md)
7. [Solvers](Documentation/lessons/obi/solvers.md)
8. [Obi and robots](Documentation/lessons/obi/robots.md)
9. [Obi and Flex](Documentation/lessons/obi/obi_and_flex.md)

### 8.3 Physics (Flex)

1. [Flex](Documentation/lessons/flex/flex.md)
2. [Solid and soft actors](Documentation/lessons/flex/solid_and_soft.md)
3. [Cloth actors](Documentation/lessons/flex/cloth.md)
4. [Fluid and source actors](Documentation/lessons/flex/fluid_and_source.md)
5. [Move, rotate, and scale Flex objects](Documentation/lessons/flex/transform.md)
6. [`FlexParticles` output data](Documentation/lessons/flex/output_data.md)
7. [Apply forces to Flex objects](Documentation/lessons/flex/forces.md)
8. [Reset a Flex scene](Documentation/lessons/flex/reset_scene.md)
8. [Other Flex commands](Documentation/lessons/flex/other_commands.md)

High-level API: [tdw_physics](https://github.com/alters-mit/tdw_physics)

## 9. Audio

1. [Overview](Documentation/lessons/audio/overview.md)
2. [Initialize audio and play .wav files](Documentation/lessons/audio/initialize_audio.md)
3. [Resonance Audio](Documentation/lessons/audio/resonance_audio.md)
4. [Recording audio](Documentation/lessons/audio/record_audio.md)
5. [Audio perception](Documentation/lessons/audio/audio_perception.md)

### 9.1 Clatter (Physically-derived audio)

1. [Overview](Documentation/lessons/clatter/overview.md)
2. [Object audio data](Documentation/lessons/clatter/clatter_objects.md)
3. [Recording Clatter audio with the `PhysicsAudioRecorder` add-on](Documentation/lessons/clatter/record_clatter.md)
4. [Clatter and Resonance Audio](Documentation/lessons/clatter/resonance_audio.md)
5. [Reset Clatter](Documentation/lessons/clatter/reset.md)
6. [Manually generate audio](Documentation/lessons/clatter/cli.md)
7. [Troubleshooting Clatter](Documentation/lessons/clatter/troubleshooting.md)
8. [How to contribute to Clatter](Documentation/lessons/clatter/contribute.md)

### 9.2 PyImpact (obsolete predecessor to Clatter)

1. [PyImpact](Documentation/lessons/py_impact/py_impact.md)
2. [PyImpact advanced](Documentation/lessons/py_impact/py_impact_advanced.md)
3. [PyImpact and Clatter](Documentation/lessons/py_impact/py_impact_and_clatter.md)

## 10. Video Recording

1. [Overview](Documentation/lessons/video/overview.md)
2. [Image-only video](Documentation/lessons/video/images.md)
3. [Video with audio](Documentation/lessons/video/audio.md)
   1. [Video with audio (Linux)](Documentation/lessons/video/screen_record_linux.md)
   2. [Video with audio (OS X)](Documentation/lessons/video/screen_record_osx.md)
   3. [Video with audio (Windows)](Documentation/lessons/video/screen_record_windows.md)

## 11. Agents

[**Overview**](Documentation/lessons/agents/overview.md)

### 11.1 Robots

1. [Overview](Documentation/lessons/robots/overview.md)
2. [The `Robot` add-on](Documentation/lessons/robots/robot_add_on.md)
3. [Robot arm add-ons](Documentation/lessons/robots/robot_arm.md)
4. [Robot collision detection](Documentation/lessons/robots/collision_detection.md)
5. [Select a robot](Documentation/lessons/robots/select_robot.md)
6. [Add your own robots to TDW](Documentation/lessons/robots/custom_robots.md)
7. [Robotics API (low-level)](Documentation/lessons/robots/custom_robots.md)
8. [Add a camera to a robot](Documentation/lessons/robots/add_camera.md)

### 11.2 Magnebots

1. [Magnebot API (external repo)](https://github.com/alters-mit/magnebot)

### 11.3 Replicants

1. [Overview](Documentation/lessons/replicants/overview.md)
2. [Actions](Documentation/lessons/replicants/actions.md)
3. [Output data](Documentation/lessons/replicants/output_data.md)
4. [Collision detection](Documentation/lessons/replicants/collision_detection.md)
5. [Movement](Documentation/lessons/replicants/movement.md)
6. [Animations](Documentation/lessons/replicants/animations.md)
7. [Arm articulation, pt. 1: Basics](Documentation/lessons/replicants/arm_articulation_1.md)
8. [Arm articulation, pt. 2: Grasp and drop objects](Documentation/lessons/replicants/arm_articulation_2.md)
9. [Arm articulation, pt. 3: Advanced topics](Documentation/lessons/replicants/arm_articulation_3.md)
10. [Arm articulation, pt. 4: Stacking objects](Documentation/lessons/replicants/arm_articulation_4.md)
11. [Head rotation](Documentation/lessons/replicants/head_rotation.md)
12. [Navigation](Documentation/lessons/replicants/navigation.md)
13. [Custom actions](Documentation/lessons/replicants/custom_actions.md)
14. [Multiple Replicants](Documentation/lessons/replicants/multiple_replicants.md)
15. [Reset](Documentation/lessons/replicants/reset.md)

### 11.4 Wheelchair Replicants

1. [Overview](Documentation/lessons/wheelchair_replicants/overview.md)
2. [Actions](Documentation/lessons/wheelchair_replicants/actions.md)
3. [Output data](Documentation/lessons/wheelchair_replicants/output_data.md)
4. [Collision detection](Documentation/lessons/wheelchair_replicants/collision_detection.md)
5. [Movement](Documentation/lessons/wheelchair_replicants/movement.md)
6. [Arm articulation, pt. 1: Basics](Documentation/lessons/wheelchair_replicants/arm_articulation_1.md)
7. [Arm articulation, pt. 2: Grasp and drop objects](Documentation/lessons/wheelchair_replicants/arm_articulation_2.md)
8. [Arm articulation, pt. 3: Advanced topics](Documentation/lessons/wheelchair_replicants/arm_articulation_3.md)
9. [Head rotation](Documentation/lessons/wheelchair_replicants/head_rotation.md)
10. [Navigation](Documentation/lessons/wheelchair_replicants/navigation.md)
11. [Custom actions](Documentation/lessons/wheelchair_replicants/custom_actions.md)
12. [Multiple Agents](Documentation/lessons/wheelchair_replicants/multiple_agents.md)
13. [Reset](Documentation/lessons/wheelchair_replicants/reset.md)

### 11.5 Drones

1. [Drones](Documentation/lessons/drone/drone.md)

### 11.6 Vehicles

1. [Vehicles](Documentation/lessons/vehicle/vehicle.md)

### 11.7 Virtual Reality (VR)

1. [Overview](Documentation/lessons/vr/overview.md)
2. [Oculus Touch](Documentation/lessons/vr/oculus_touch.md)
3. [Oculus Leap Motion](Documentation/lessons/vr/oculus_leap_motion.md)
4. [FOVE Leap Motion](Documentation/lessons/vr/fove_leap_motion.md)

### 11.8 Keyboard and Mouse

1. [Overview](Documentation/lessons/keyboard_and_mouse/overview.md)
2. [Mouse input](Documentation/lessons/keyboard_and_mouse/mouse.md)
3. [The `FirstPersonAvatar`](Documentation/lessons/keyboard_and_mouse/first_person_avatar.md)
4. [Keyboard input](Documentation/lessons/keyboard_and_mouse/keyboard.md)

### 11.9 Embodied avatars

1. [The `EmbodiedAvatar`](Documentation/lessons/embodied_avatars/embodied_avatar.md)

## 12. Multi-agent simulations

1. [Overview](Documentation/lessons/multi_agent/overview.md)
2. [Custom agent classes](Documentation/lessons/multi_agent/custom_agent_classes.md)

## 13. Navigation

1. [Overview](Documentation/lessons/navigation/overview.md)
2. [NavMesh pathfinding](Documentation/lessons/navigation/nav_mesh.md)
3. [Occupancy maps](Documentation/lessons/navigation/occupancy_maps.md)

## 14. User Interface (UI)

1. [Overview](Documentation/lessons/ui/overview.md)
2. [The `UI` add-on](Documentation/lessons/ui/ui.md)
3. [UI Widgets](Documentation/lessons/ui/widgets.md)

## 15. Non-physics objects

### 15.1 Non-physics humanoids

1. [Overview](Documentation/lessons/non_physics_humanoids/overview.md)
2. [SMPL humanoids](Documentation/lessons/non_physics_humanoids/smpl.md)
3. [Create custom non-physics humanoids](Documentation/lessons/non_physics_humanoids/custom_humanoids.md)
4. [Create custom humanoid animations](Documentation/lessons/non_physics_humanoids/custom_animations.md)

### 15.2 Misc. non-physics objects

1. [Overview](Documentation/lessons/non_physics/overview.md)
2. [Position markers](Documentation/lessons/non_physics/position_markers.md)
3. [Line renderers](Documentation/lessons/non_physics/line_renderers.md)
4. [Textured quads](Documentation/lessons/non_physics/textured_quads.md)
5. [Compass rose](Documentation/lessons/non_physics/compass_rose.md)
6. [Visual Effects](Documentation/lessons/non_physics/visual_effects.md)
7. [The `FloorplanFlood` add-on](Documentation/lessons/non_physics/floorplan_flood.md)
8. [Empty objects](Documentation/lessons/non_physics/empty_objects.md)

## 16. Misc. other topics

1. [C# source code](Documentation/lessons/misc/c_sharp_sources.md)
2. [Freezing your code](Documentation/lessons/misc/freeze.md)
3. [Download asset bundles](Documentation/lessons/misc/download_asset_bundles.md)

# API Documentation

## Command API

- [Command API](Documentation/api/command_api.md)
- [Output Data](Documentation/api/output_data.md)

## `tdw` module API

**tdw**

- [AudioConstants](Documentation/python/audio_constants.md)
- [AudioUtils](Documentation/python/audio_utils.md)
- [CardinalDirection](Documentation/python/cardinal_direction.md)
- [Controller](Documentation/python/controller.md)
- [IntPair](Documentation/python/int_pair.md)
- [OrdinalDirection](Documentation/python/ordinal_direction.md)
- [QuaternionUtils](Documentation/python/quaternion_utils.md)
- [RemoteBuildLauncher](Documentation/python/remote_build_launcher.md)
- [TDWUtils](Documentation/python/tdw_utils.md)
- [TypeAliases](Documentation/python/type_aliases.md)

**tdw.add_ons**

- [AddOn](Documentation/python/add_ons/add_on.md)
- [AudioInitializer](Documentation/python/add_ons/audio_initializer.md)
- [AudioInitializerBase](Documentation/python/add_ons/audio_initializer_base.md)
- [Autohand](Documentation/python/add_ons/autohand.md)
- [AvatarBody](Documentation/python/add_ons/avatar_body.md)
- [Benchmark](Documentation/python/add_ons/benchmark.md)
- [CinematicCamera](Documentation/python/add_ons/cinematic_camera.md)
- [Clatter](Documentation/python/add_ons/clatter.md)
- [CollisionManager](Documentation/python/add_ons/collision_manager.md)
- [CompositeObjectManager](Documentation/python/add_ons/composite_object_manager.md)
- [ContainerManager](Documentation/python/add_ons/container_manager.md)
- [Drone](Documentation/python/add_ons/drone.md)
- [EmbodiedAvatar](Documentation/python/add_ons/embodied_avatar.md)
- [EmptyObjectManager](Documentation/python/add_ons/empty_object_manager.md)
- [FirstPersonAvatar](Documentation/python/add_ons/first_person_avatar.md)
- [Floorplan](Documentation/python/add_ons/floorplan.md)
- [FloorplanFlood](Documentation/python/add_ons/floorplan_flood.md)
- [FoveLeapMotion](Documentation/python/add_ons/fove_leap_motion.md)
- [ImageCapture](Documentation/python/add_ons/image_capture.md)
- [InteriorSceneLighting](Documentation/python/add_ons/interior_scene_lighting.md)
- [JsonWriter](Documentation/python/add_ons/json_writer.md)
- [Keyboard](Documentation/python/add_ons/keyboard.md)
- [LeapMotion](Documentation/python/add_ons/leap_motion.md)
- [LisdfReader](Documentation/python/add_ons/lisdf_reader.md)
- [Logger](Documentation/python/add_ons/logger.md)
- [LogPlayback](Documentation/python/add_ons/log_playback.md)
- [ModelVerifier](Documentation/python/add_ons/model_verifier.md)
- [Mouse](Documentation/python/add_ons/mouse.md)
- [NavMesh](Documentation/python/add_ons/nav_mesh.md)
- [Obi](Documentation/python/add_ons/obi.md)
- [ObjectManager](Documentation/python/add_ons/object_manager.md)
- [OccupancyMap](Documentation/python/add_ons/occupancy_map.md)
- [OculusLeapMotion](Documentation/python/add_ons/oculus_leap_motion.md)
- [OculusTouch](Documentation/python/add_ons/oculus_touch.md)
- [OutputDataWriter](Documentation/python/add_ons/output_data_writer.md)
- [PhysicsAudioRecorder](Documentation/python/add_ons/physics_audio_recorder.md)
- [ProcGenKitchen](Documentation/python/add_ons/proc_gen_kitchen.md)
- [PyImpact](Documentation/python/add_ons/py_impact.md)
- [Replicant](Documentation/python/add_ons/replicant.md)
- [ReplicantBase](Documentation/python/add_ons/replicant_base.md)
- [ResonanceAudioInitializer](Documentation/python/add_ons/resonance_audio_initializer.md)
- [Robot](Documentation/python/add_ons/robot.md)
- [RobotArm](Documentation/python/add_ons/robot_arm.md)
- [RobotBase](Documentation/python/add_ons/robot_base.md)
- [StepPhysics](Documentation/python/add_ons/step_physics.md)
- [ThirdPersonCamera](Documentation/python/add_ons/third_person_camera.md)
- [ThirdPersonCameraBase](Documentation/python/add_ons/third_person_camera_base.md)
- [TriggerCollisionManager](Documentation/python/add_ons/trigger_collision_manager.md)
- [UI](Documentation/python/add_ons/ui.md)
- [Vehicle](Documentation/python/add_ons/vehicle.md)
- [VR](Documentation/python/add_ons/vr.md)
- [VrayExporter](Documentation/python/add_ons/vray_exporter.md)
- [WheelchairReplicant](Documentation/python/add_ons/wheelchair_replicant.md)
- [Writer](Documentation/python/add_ons/writer.md)

**tdw.add_ons.ui_widgets**

- [LoadingScreen](Documentation/python/add_ons/ui_widgets/loading_screen.md)
- [ProgressBar](Documentation/python/add_ons/ui_widgets/progress_bar.md)
- [TimerBar](Documentation/python/add_ons/ui_widgets/timer_bar.md)

**tdw.agent_data**

- [AgentDynamic](Documentation/python/agent_data/agent_dynamic.md)

**tdw.asset_bundle_creator**

- [AnimationCreator](Documentation/python/asset_bundle_creator/animation_creator.md)
- [AssetBundleCreator](Documentation/python/asset_bundle_creator/asset_bundle_creator.md)
- [CompositeObjectCreator](Documentation/python/asset_bundle_creator/composite_object_creator.md)
- [HumanoidCreator](Documentation/python/asset_bundle_creator/humanoid_creator.md)
- [HumanoidCreatorBase](Documentation/python/asset_bundle_creator/humanoid_creator_base.md)
- [ModelCreator](Documentation/python/asset_bundle_creator/model_creator.md)
- [RobotCreator](Documentation/python/asset_bundle_creator/robot_creator.md)

**tdw.backend**

- [Update](Documentation/python/backend/update.md)

**tdw.collision_data**

- [CollisionBase](Documentation/python/collision_data/collision_base.md)
- [CollisionObjEnv](Documentation/python/collision_data/collision_obj_env.md)
- [CollisionObjObj](Documentation/python/collision_data/collision_obj_obj.md)
- [TriggerColliderShape](Documentation/python/collision_data/trigger_collider_shape.md)
- [TriggerCollisionEvent](Documentation/python/collision_data/trigger_collision_event.md)

**tdw.container_data**

- [BoxContainer](Documentation/python/container_data/box_container.md)
- [ContainerShape](Documentation/python/container_data/container_shape.md)
- [ContainerTag](Documentation/python/container_data/container_tag.md)
- [ContainmentEvent](Documentation/python/container_data/containment_event.md)
- [CylinderContainer](Documentation/python/container_data/cylinder_container.md)
- [SphereContainer](Documentation/python/container_data/sphere_container.md)

**tdw.drone**

- [DroneDynamic](Documentation/python/drone/drone_dynamic.md)

**tdw.flex_data**

- [FluidType](Documentation/python/flex_data/fluid_type.md)

**tdw.lerp**

- [Lerpable](Documentation/python/lerp/lerpable.md)
- [LerpableFloat](Documentation/python/lerp/lerpable_float.md)
- [LerpableVector](Documentation/python/lerp/lerpable_vector.md)

**tdw.librarian**

- [DroneLibrarian](Documentation/python/librarian/drone_librarian.md)
- [HdriSkyboxLibrarian](Documentation/python/librarian/hdri_skybox_librarian.md)
- [HumanoidAnimationLibrarian](Documentation/python/librarian/humanoid_animation_librarian.md)
- [HumanoidLibrarian](Documentation/python/librarian/humanoid_librarian.md)
- [MaterialLibrarian](Documentation/python/librarian/material_librarian.md)
- [ModelLibrarian](Documentation/python/librarian/model_librarian.md)
- [RobotLibrarian](Documentation/python/librarian/robot_librarian.md)
- [SceneLibrarian](Documentation/python/librarian/scene_librarian.md)
- [VehicleLibrarian](Documentation/python/librarian/vehicle_librarian.md)
- [VisualEffectLibrarian](Documentation/python/librarian/visual_effect_librarian.md)

**tdw.lisdf_data**

- [LisdfRobotMetadata](Documentation/python/lisdf_data/lisdf_robot_metadata.md)

**tdw.model_tests**

- [MissingMaterials](Documentation/python/model_tests/missing_materials.md)
- [ModelReport](Documentation/python/model_tests/model_report.md)
- [ModelTest](Documentation/python/model_tests/model_test.md)
- [PhysicsQuality](Documentation/python/model_tests/physics_quality.md)
- [RotateObjectTest](Documentation/python/model_tests/rotate_object_test.md)

**tdw.obi_data**

- [ForceMode](Documentation/python/obi_data/force_mode.md)
- [ObiActor](Documentation/python/obi_data/obi_actor.md)
- [ObiBackend](Documentation/python/obi_data/obi_backend.md)
- [WindSource](Documentation/python/obi_data/wind_source.md)

**tdw.obi_data.cloth**

- [ClothMaterial](Documentation/python/obi_data/cloth/cloth_material.md)
- [SheetType](Documentation/python/obi_data/cloth/sheet_type.md)
- [TetherParticleGroup](Documentation/python/obi_data/cloth/tether_particle_group.md)
- [TetherType](Documentation/python/obi_data/cloth/tether_type.md)
- [VolumeType](Documentation/python/obi_data/cloth/volume_type.md)

**tdw.obi_data.collision_materials**

- [CollisionMaterial](Documentation/python/obi_data/collision_materials/collision_material.md)
- [MaterialCombineMode](Documentation/python/obi_data/collision_materials/material_combine_mode.md)

**tdw.obi_data.fluids**

- [CubeEmitter](Documentation/python/obi_data/fluids/cube_emitter.md)
- [DiskEmitter](Documentation/python/obi_data/fluids/disk_emitter.md)
- [EdgeEmitter](Documentation/python/obi_data/fluids/edge_emitter.md)
- [EmitterSamplingMethod](Documentation/python/obi_data/fluids/emitter_sampling_method.md)
- [EmitterShape](Documentation/python/obi_data/fluids/emitter_shape.md)
- [Fluid](Documentation/python/obi_data/fluids/fluid.md)
- [FluidBase](Documentation/python/obi_data/fluids/fluid_base.md)
- [GranularFluid](Documentation/python/obi_data/fluids/granular_fluid.md)
- [SphereEmitter](Documentation/python/obi_data/fluids/sphere_emitter.md)

**tdw.object_data**

- [Bound](Documentation/python/object_data/bound.md)
- [ObjectStatic](Documentation/python/object_data/object_static.md)
- [Rigidbody](Documentation/python/object_data/rigidbody.md)
- [Transform](Documentation/python/object_data/transform.md)

**tdw.object_data.composite_object**

- [CompositeObjectDynamic](Documentation/python/object_data/composite_object/composite_object_dynamic.md)
- [CompositeObjectStatic](Documentation/python/object_data/composite_object/composite_object_static.md)

**tdw.object_data.composite_object.sub_object**

- [HingeDynamic](Documentation/python/object_data/composite_object/sub_object/hinge_dynamic.md)
- [HingeStatic](Documentation/python/object_data/composite_object/sub_object/hinge_static.md)
- [HingeStaticBase](Documentation/python/object_data/composite_object/sub_object/hinge_static_base.md)
- [LightDynamic](Documentation/python/object_data/composite_object/sub_object/light_dynamic.md)
- [LightStatic](Documentation/python/object_data/composite_object/sub_object/light_static.md)
- [MotorStatic](Documentation/python/object_data/composite_object/sub_object/motor_static.md)
- [NonMachineStatic](Documentation/python/object_data/composite_object/sub_object/non_machine_static.md)
- [PrismaticJointStatic](Documentation/python/object_data/composite_object/sub_object/prismatic_joint_static.md)
- [SpringStatic](Documentation/python/object_data/composite_object/sub_object/spring_static.md)
- [SubObjectDynamic](Documentation/python/object_data/composite_object/sub_object/sub_object_dynamic.md)
- [SubObjectStatic](Documentation/python/object_data/composite_object/sub_object/sub_object_static.md)

**tdw.physics_audio**

- [AudioMaterial](Documentation/python/physics_audio/audio_material.md)
- [Base64Sound](Documentation/python/physics_audio/base64_sound.md)
- [ClatterObject](Documentation/python/physics_audio/clatter_object.md)
- [CollisionAudioEvent](Documentation/python/physics_audio/collision_audio_event.md)
- [CollisionAudioInfo](Documentation/python/physics_audio/collision_audio_info.md)
- [CollisionAudioType](Documentation/python/physics_audio/collision_audio_type.md)
- [ImpactMaterial](Documentation/python/physics_audio/impact_material.md)
- [Modes](Documentation/python/physics_audio/modes.md)
- [ObjectAudioStatic](Documentation/python/physics_audio/object_audio_static.md)
- [ScrapeMaterial](Documentation/python/physics_audio/scrape_material.md)
- [ScrapeModel](Documentation/python/physics_audio/scrape_model.md)
- [ScrapeSubObject](Documentation/python/physics_audio/scrape_sub_object.md)

**tdw.proc_gen.arrangements**

- [Arrangement](Documentation/python/proc_gen/arrangements/arrangement.md)
- [ArrangementAlongWall](Documentation/python/proc_gen/arrangements/arrangement_along_wall.md)
- [ArrangementWithRootObject](Documentation/python/proc_gen/arrangements/arrangement_with_root_object.md)
- [Basket](Documentation/python/proc_gen/arrangements/basket.md)
- [CupAndCoaster](Documentation/python/proc_gen/arrangements/cup_and_coaster.md)
- [Dishwasher](Documentation/python/proc_gen/arrangements/dishwasher.md)
- [KitchenCabinet](Documentation/python/proc_gen/arrangements/kitchen_cabinet.md)
- [KitchenCounter](Documentation/python/proc_gen/arrangements/kitchen_counter.md)
- [KitchenCounterTop](Documentation/python/proc_gen/arrangements/kitchen_counter_top.md)
- [KitchenTable](Documentation/python/proc_gen/arrangements/kitchen_table.md)
- [Microwave](Documentation/python/proc_gen/arrangements/microwave.md)
- [Painting](Documentation/python/proc_gen/arrangements/painting.md)
- [Plate](Documentation/python/proc_gen/arrangements/plate.md)
- [Radiator](Documentation/python/proc_gen/arrangements/radiator.md)
- [Refrigerator](Documentation/python/proc_gen/arrangements/refrigerator.md)
- [Shelf](Documentation/python/proc_gen/arrangements/shelf.md)
- [SideTable](Documentation/python/proc_gen/arrangements/side_table.md)
- [Sink](Documentation/python/proc_gen/arrangements/sink.md)
- [StackOfPlates](Documentation/python/proc_gen/arrangements/stack_of_plates.md)
- [Stool](Documentation/python/proc_gen/arrangements/stool.md)
- [Stove](Documentation/python/proc_gen/arrangements/stove.md)
- [Suitcase](Documentation/python/proc_gen/arrangements/suitcase.md)
- [TableAndChairs](Documentation/python/proc_gen/arrangements/table_and_chairs.md)
- [TableSetting](Documentation/python/proc_gen/arrangements/table_setting.md)
- [Void](Documentation/python/proc_gen/arrangements/void.md)
- [WallCabinet](Documentation/python/proc_gen/arrangements/wall_cabinet.md)

**tdw.proc_gen.arrangements.cabinetry**

- [Cabinetry](Documentation/python/proc_gen/arrangements/cabinetry/cabinetry.md)
- [CabinetryType](Documentation/python/proc_gen/arrangements/cabinetry/cabinetry_type.md)

**tdw.release**

- [Build](Documentation/python/release/build.md)
- [PyPi](Documentation/python/release/pypi.md)

**tdw.replicant**

- [ActionStatus](Documentation/python/replicant/action_status.md)
- [Arm](Documentation/python/replicant/arm.md)
- [CollisionDetection](Documentation/python/replicant/collision_detection.md)
- [ImageFrequency](Documentation/python/replicant/image_frequency.md)
- [ReplicantBodyPart](Documentation/python/replicant/replicant_body_part.md)
- [ReplicantDynamic](Documentation/python/replicant/replicant_dynamic.md)
- [ReplicantStatic](Documentation/python/replicant/replicant_static.md)

**tdw.replicant.actions**

- [Action](Documentation/python/replicant/actions/action.md)
- [Animate](Documentation/python/replicant/actions/animate.md)
- [ArmMotion](Documentation/python/replicant/actions/arm_motion.md)
- [DoNothing](Documentation/python/replicant/actions/do_nothing.md)
- [Drop](Documentation/python/replicant/actions/drop.md)
- [Grasp](Documentation/python/replicant/actions/grasp.md)
- [HeadMotion](Documentation/python/replicant/actions/head_motion.md)
- [IkMotion](Documentation/python/replicant/actions/ik_motion.md)
- [LookAt](Documentation/python/replicant/actions/look_at.md)
- [MoveBy](Documentation/python/replicant/actions/move_by.md)
- [MoveTo](Documentation/python/replicant/actions/move_to.md)
- [ReachFor](Documentation/python/replicant/actions/reach_for.md)
- [ReachForWithPlan](Documentation/python/replicant/actions/reach_for_with_plan.md)
- [ResetArm](Documentation/python/replicant/actions/reset_arm.md)
- [ResetHead](Documentation/python/replicant/actions/reset_head.md)
- [RotateHead](Documentation/python/replicant/actions/rotate_head.md)
- [TurnBy](Documentation/python/replicant/actions/turn_by.md)
- [TurnTo](Documentation/python/replicant/actions/turn_to.md)

**tdw.replicant.ik_plans**

- [IkPlan](Documentation/python/replicant/ik_plans/ik_plan.md)
- [IkPlanType](Documentation/python/replicant/ik_plans/ik_plan_type.md)
- [Reset](Documentation/python/replicant/ik_plans/reset.md)
- [VerticalHorizontal](Documentation/python/replicant/ik_plans/vertical_horizontal.md)

**tdw.robot_data**

- [Drive](Documentation/python/robot_data/drive.md)
- [JointDynamic](Documentation/python/robot_data/joint_dynamic.md)
- [JointStatic](Documentation/python/robot_data/joint_static.md)
- [JointType](Documentation/python/robot_data/joint_type.md)
- [NonMoving](Documentation/python/robot_data/non_moving.md)
- [RobotDynamic](Documentation/python/robot_data/robot_dynamic.md)
- [RobotStatic](Documentation/python/robot_data/robot_static.md)

**tdw.scene_data**

- [InteriorRegion](Documentation/python/scene_data/interior_region.md)
- [RegionBounds](Documentation/python/scene_data/region_bounds.md)
- [Room](Documentation/python/scene_data/room.md)
- [SceneBounds](Documentation/python/scene_data/scene_bounds.md)

**tdw.vehicle**

- [VehicleDynamic](Documentation/python/vehicle/vehicle_dynamic.md)

**tdw.vray_data**

- [VrayMatrix](Documentation/python/vray_data/vray_matrix.md)

**tdw.vr_data**

- [FingerBone](Documentation/python/vr_data/finger_bone.md)
- [OculusTouchButton](Documentation/python/vr_data/oculus_touch_button.md)
- [RigType](Documentation/python/vr_data/rig_type.md)

**tdw.vr_data.fove**

- [CalibrationMethod](Documentation/python/vr_data/fove/calibration_method.md)
- [CalibrationSphere](Documentation/python/vr_data/fove/calibration_sphere.md)
- [CalibrationState](Documentation/python/vr_data/fove/calibration_state.md)
- [Eye](Documentation/python/vr_data/fove/eye.md)
- [EyeByEyeCalibration](Documentation/python/vr_data/fove/eye_by_eye_calibration.md)
- [EyeState](Documentation/python/vr_data/fove/eye_state.md)
- [EyeTorsionCalibration](Documentation/python/vr_data/fove/eye_torsion_calibration.md)

**tdw.wheelchair_replicant**

- [WheelValues](Documentation/python/wheelchair_replicant/wheel_values.md)

**tdw.wheelchair_replicant.actions**

- [MoveBy](Documentation/python/wheelchair_replicant/actions/move_by.md)
- [MoveTo](Documentation/python/wheelchair_replicant/actions/move_to.md)
- [ReachFor](Documentation/python/wheelchair_replicant/actions/reach_for.md)
- [TurnBy](Documentation/python/wheelchair_replicant/actions/turn_by.md)
- [TurnTo](Documentation/python/wheelchair_replicant/actions/turn_to.md)
- [WheelchairMotion](Documentation/python/wheelchair_replicant/actions/wheelchair_motion.md)

# Performance benchmarks
1. [Performance benchmarks](Documentation/benchmark/benchmark.md)
2. [Image capture](Documentation/benchmark/image_capture.md)
3. [Object data](Documentation/benchmark/object_data.md)
4. [Command deserialization](Documentation/benchmark/command_deserialization.md)


Python Client for Google BigQuery
=================================

|GA| |pypi| |versions|

Querying massive datasets can be time consuming and expensive without the
right hardware and infrastructure. Google `BigQuery`_ solves this problem by
enabling super-fast, SQL queries against append-mostly tables, using the
processing power of Google's infrastructure.

-  `Client Library Documentation`_
-  `Product Documentation`_

.. |GA| image:: https://img.shields.io/badge/support-GA-gold.svg
   :target: https://github.com/googleapis/google-cloud-python/blob/main/README.rst#general-availability
.. |pypi| image:: https://img.shields.io/pypi/v/google-cloud-bigquery.svg
   :target: https://pypi.org/project/google-cloud-bigquery/
.. |versions| image:: https://img.shields.io/pypi/pyversions/google-cloud-bigquery.svg
   :target: https://pypi.org/project/google-cloud-bigquery/
.. _BigQuery: https://cloud.google.com/bigquery/what-is-bigquery
.. _Client Library Documentation: https://googleapis.dev/python/bigquery/latest
.. _Product Documentation: https://cloud.google.com/bigquery/docs/reference/v2/

Quick Start
-----------

In order to use this library, you first need to go through the following steps:

1. `Select or create a Cloud Platform project.`_
2. `Enable billing for your project.`_
3. `Enable the Google Cloud BigQuery API.`_
4. `Setup Authentication.`_

.. _Select or create a Cloud Platform project.: https://console.cloud.google.com/project
.. _Enable billing for your project.: https://cloud.google.com/billing/docs/how-to/modify-project#enable_billing_for_a_project
.. _Enable the Google Cloud BigQuery API.:  https://cloud.google.com/bigquery
.. _Setup Authentication.: https://googleapis.dev/python/google-api-core/latest/auth.html

Installation
~~~~~~~~~~~~

Install this library in a `virtualenv`_ using pip. `virtualenv`_ is a tool to
create isolated Python environments. The basic problem it addresses is one of
dependencies and versions, and indirectly permissions.

With `virtualenv`_, it's possible to install this library without needing system
install permissions, and without clashing with the installed system
dependencies.

.. _`virtualenv`: https://virtualenv.pypa.io/en/latest/

Supported Python Versions
^^^^^^^^^^^^^^^^^^^^^^^^^
Python >= 3.7

Unsupported Python Versions
^^^^^^^^^^^^^^^^^^^^^^^^^^^
Python == 2.7, Python == 3.5, Python == 3.6.

The last version of this library compatible with Python 2.7 and 3.5 is
`google-cloud-bigquery==1.28.0`.

Mac/Linux
^^^^^^^^^

.. code-block:: console

    pip install virtualenv
    virtualenv <your-env>
    source <your-env>/bin/activate
    <your-env>/bin/pip install google-cloud-bigquery

Windows
^^^^^^^

.. code-block:: console

    pip install virtualenv
    virtualenv <your-env>
    <your-env>\Scripts\activate
    <your-env>\Scripts\pip.exe install google-cloud-bigquery

Example Usage
-------------

Perform a query
~~~~~~~~~~~~~~~

.. code:: python

    from google.cloud import bigquery

    client = bigquery.Client()

    # Perform a query.
    QUERY = (
        'SELECT name FROM `bigquery-public-data.usa_names.usa_1910_2013` '
        'WHERE state = "TX" '
        'LIMIT 100')
    query_job = client.query(QUERY)  # API request
    rows = query_job.result()  # Waits for query to finish

    for row in rows:
        print(row.name)

Instrumenting With OpenTelemetry
--------------------------------

This application uses `OpenTelemetry`_ to output tracing data from
API calls to BigQuery. To enable OpenTelemetry tracing in
the BigQuery client the following PyPI packages need to be installed:

.. _OpenTelemetry: https://opentelemetry.io

.. code-block:: console

    pip install google-cloud-bigquery[opentelemetry] opentelemetry-exporter-gcp-trace

After installation, OpenTelemetry can be used in the BigQuery
client and in BigQuery jobs. First, however, an exporter must be
specified for where the trace data will be outputted to. An
example of this can be found here:

.. code-block:: python

    from opentelemetry import trace
    from opentelemetry.sdk.trace import TracerProvider
    from opentelemetry.sdk.trace.export import BatchSpanProcessor
    from opentelemetry.exporter.cloud_trace import CloudTraceSpanExporter
    tracer_provider = TracerProvider()
    tracer_provider = BatchSpanProcessor(CloudTraceSpanExporter())
    trace.set_tracer_provider(TracerProvider())

In this example all tracing data will be published to the Google
`Cloud Trace`_ console. For more information on OpenTelemetry, please consult the `OpenTelemetry documentation`_.

.. _OpenTelemetry documentation: https://opentelemetry-python.readthedocs.io
.. _Cloud Trace: https://cloud.google.com/trace


[![Tools](https://github.com/google/digitalbuildings/actions/workflows/tools.yml/badge.svg)](https://github.com/google/digitalbuildings/actions/workflows/tools.yml)
![Ontology Type Validator](https://github.com/google/digitalbuildings/workflows/Ontology%20Type%20Validator/badge.svg)
![Node.js CI](https://github.com/google/digitalbuildings/workflows/Node.js%20CI/badge.svg)
[![GitHub stars](https://img.shields.io/github/stars/google/digitalbuildings.svg)](https://github.com/google/digitalbuildings/stargazers)
[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)

# Digital Buildings Project

The Digital Buildings project is an open-source, Apache-licensed effort to create a uniform schema and toolset for representing structured information about buildings and building-installed equipment. A version of the Digital Buildings ontology and toolset is currently being used by Google to manage buildings in its portfolio.

The Digital Buildings project originated from the need to manage a very large and heterogeneous building portfolio in a scalable way. The project aims to enable management applications and analyses that are trivially portable between buildings. This goal is achieved through a combination of semantically-expressive abstract modeling, an easy-to-use configuration language, and robust validation tooling. Digital Buildings work has been inspired by [Project Haystack](https://project-haystack.org/tag) and [BrickSchema](https://brickschema.org/) and maintains cross-compatibility and/or convergence as a long-term objective.

In creating the Digital Buildings project, we have considered the following:

* Human readability
* Machine readability and interpretation
* Composable functionality
* Dimensional analysis
* Correctness validation
* Cross-compatibility

## Project Structure

This project is structured as follows:
*  An [ontology](./ontology/README.md) that defines the parameters of the semantic data model ("Terminology box") and tools for building, validating, and associating real equipment with a specific model. It contains the following formats:
   * [YAML format](./ontology/yaml/README.md)
   * [RDF/OWL format](./ontology/rdf/README.md)

* A [model instance configuration](./ontology/docs/building_config.md) (a.k.a building configuration file) that contains a mapping between the ontology and the "raw" real-world data. Building configuration files are the "Assertion box."
* Tools that enable the following:
  * [**ABEL**](./tools/abel/README.md)**:** facilitates easier building configration construction by converting from a templatized Google Sheet to a [building configuration file](./ontology/docs/building_config.md) (and from a building configuration file back to a Google Sheet).
  * [**Explorer**](./tools/explorer/README.md)**:** allows users to explore ontology type fields and compare ontology types to each other.
  * [**Instance Validator**](./tools/validators/ontology_validator/README.md)**:** validates a concrete application (instance) of DBO (i.e., a building configuration file) with optional telemetry validation.
  * [**Ontology Validator**](./tools/validators/ontology_validator/README.md)**:** validates the ontology upon a change or an extension (currently supports YAML format only).
  * [**RDF/OWL Generator**](./tools/rdf_generator/README.md)**:** generates an RDF version from the YAML ontology files.
* An [Internal Building Representation (IBR)](./ibr/README.md) file format to represent data from different verticals such as spatial or assets.

## Learning Modules
The learning modules provide an overview of the following key concepts:
* The main concepts and components of the Digital Buildings Ontology
* How to model entities and extend types in the ontology
* The components of building configuration files
* How to use the validation tools for ontology extensions and building configuration files

### Module 1: Digital Buildings Ontology (DBO)
In this module, you’ll fully explore the core modeling and organizational concepts of the DBO. These are essential concepts for data modeling and creating building configuration files.

* [Lesson 1: Introduction to the DBO](./ontology/docs/learning/Module_1_Lesson_1_Introduction_to_the_DBO.pdf)
* [Lesson 2: Conceptual model](./ontology/docs/learning/Module_1_Lesson_2_Conceptual_model.pdf)
* [Lesson 3: Subfields](./ontology/docs/learning/Module_1_Lesson_3_Subfields.pdf)
* [Lesson 4: Fields](./ontology/docs/learning/Module_1_Lesson_4_Fields.pdf)
* [Lesson 5: States and multi-states](./ontology/docs/learning/Module_1_Lesson_5_States_and_multistates.pdf)
* [Lesson 6: Entity types](./ontology/docs/learning/Module_1_Lesson_6_Entity_types.pdf)
* [Lesson 7: Mappings](./ontology/docs/learning/Module_1_Lesson_7_Mappings.pdf)
* [Lesson 8: Connections](./ontology/docs/learning/Module_1_Lesson_8_Connections.pdf)
* [Lesson 9: Namespaces](./ontology/docs/learning/Module_1_Lesson_9_Namespaces.pdf)

### Module 2: Data Modeling with the DBO

In this module, you’ll deepen your understanding of the DBO and practice applying it. Through several hands-on activities, you'll walk through the recommended workflow for creating a building configuration file

* [Lesson 1: Get ready to data model](./ontology/docs/learning/Module_2_Lesson_1_Get_ready_to_data_model.pdf)
* [Lesson 2: Determine which devices need to be modeled](./ontology/docs/learning/Module_2_Lesson_2_Determine_which_devices_need_to_be_modeled.pdf)
* [Lesson 3: Determine which data points are required](./ontology/docs/learning/Module_2_Lesson_3_Determine_which_data_points_are_required.pdf)
* [Lesson 4: Name each data point using the DBO](./ontology/docs/learning/Module_2_Lesson_4_Name_each_data_point_using_the_DBO.pdf)
* [Lesson 5: Propose an ontology extension](./ontology/docs/learning/Module_2_Lesson_5_Propose_an_ontology_extension.pdf)
* [Lesson 6: Construct and finalize the building configuration file](./ontology/docs/learning/Module_2_Lesson_6_Construct_and_finalize_the_building_configuration_file.pdf)
* [Lesson 7: Validate the instance and telemetry](./ontology/docs/learning/Module_2_Lesson_7_Validate_the_instance_and_telemetry.pdf)

## Issues
Please post issues in the [Issues](https://github.com/google/digitalbuildings/issues) section.

## Discussion
Our team has created an open mailing list to discuss Google's Digital Building effort. The discussion could include general questions, standards, APIs, and more. Join the discussion here: [google-digital-building-discuss@googlegroups.com](mailto:google-digital-building-discuss@googlegroups.com).

Members are expected to adhere to this code of conduct: [https://opensource.google.com/conduct](https://opensource.google.com/conduct).

## How to Contribute

Please see the [contribution](CONTRIBUTING.md) section.

## License
```
Copyright 2023 Google LLC

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

    https://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
```

## Publications & Talks
* [Québec Bâtiment Vert et Intelligent 2020](https://www.eventbrite.ca/e/billets-rendez-vous-annuel-quebec-bvi-presente-par-google-128034116489)
* [ISWC 2020](http://ceur-ws.org/Vol-2721/paper510.pdf)
* [LDAC 2020](http://linkedbuildingdata.net/ldac2020/abstracts.html#industry10)
* [ICML 2020](http://proceedings.mlr.press/v119/sipple20a/sipple20a.pdf)
* [Semantics 2019](https://2019.semantics.cc/role-semantics-googles-smart-building-platform)
* [Google Cloud Next'19](https://youtu.be/Zz6jkLYkzSQ)


![PyBaMM_logo](https://user-images.githubusercontent.com/20817509/107091287-8ad46a80-67cf-11eb-86f5-7ebef7c72a1e.png)

#

[![Powered by NumFOCUS](https://img.shields.io/badge/powered%20by-NumFOCUS-orange.svg?style=flat&colorA=E1523D&colorB=007D8A)](http://numfocus.org)
[![Scheduled](https://github.com/pybamm-team/PyBaMM/actions/workflows/run_periodic_tests.yml/badge.svg?branch=develop)](https://github.com/pybamm-team/PyBaMM/actions/workflows/run_periodic_tests.yml)
[![readthedocs](https://readthedocs.org/projects/pybamm/badge/?version=latest)](https://docs.pybamm.org/en/latest/?badge=latest)
[![codecov](https://codecov.io/gh/pybamm-team/PyBaMM/branch/main/graph/badge.svg)](https://codecov.io/gh/pybamm-team/PyBaMM)
[![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/pybamm-team/PyBaMM/blob/main/)
[![DOI](https://zenodo.org/badge/DOI/10.5334/jors.309.svg)](https://doi.org/10.5334/jors.309)
[![release](https://img.shields.io/github/v/release/pybamm-team/PyBaMM?color=yellow)](https://github.com/pybamm-team/PyBaMM/releases)
[![code style](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/charliermarsh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)

[![All Contributors](https://img.shields.io/badge/all_contributors-87-orange.svg)](#-contributors)

# PyBaMM

PyBaMM (Python Battery Mathematical Modelling) is an open-source battery simulation package
written in Python. Our mission is to accelerate battery modelling research by
providing open-source tools for multi-institutional, interdisciplinary collaboration.
Broadly, PyBaMM consists of
(i) a framework for writing and solving systems
of differential equations,
(ii) a library of battery models and parameters, and
(iii) specialized tools for simulating battery-specific experiments and visualizing the results.
Together, these enable flexible model definitions and fast battery simulations, allowing users to
explore the effect of different battery designs and modeling assumptions under a variety of operating scenarios.

[//]: # "numfocus-fiscal-sponsor-attribution"

PyBaMM uses an [open governance model](https://pybamm.org/governance/)
and is fiscally sponsored by [NumFOCUS](https://numfocus.org/). Consider making
a [tax-deductible donation](https://numfocus.org/donate-for-pybamm) to help the project
pay for developer time, professional services, travel, workshops, and a variety of other needs.

## 💻 Using PyBaMM

The easiest way to use PyBaMM is to run a 1C constant-current discharge with a model of your choice with all the default settings:

```python3
import pybamm

model = pybamm.lithium_ion.DFN()  # Doyle-Fuller-Newman model
sim = pybamm.Simulation(model)
sim.solve([0, 3600])  # solve for 1 hour
sim.plot()
```

or simulate an experiment such as a constant-current discharge followed by a constant-current-constant-voltage charge:

```python3
import pybamm

experiment = pybamm.Experiment(
    [
        (
            "Discharge at C/10 for 10 hours or until 3.3 V",
            "Rest for 1 hour",
            "Charge at 1 A until 4.1 V",
            "Hold at 4.1 V until 50 mA",
            "Rest for 1 hour",
        )
    ]
    * 3,
)
model = pybamm.lithium_ion.DFN()
sim = pybamm.Simulation(model, experiment=experiment, solver=pybamm.CasadiSolver())
sim.solve()
sim.plot()
```

However, much greater customisation is available. It is possible to change the physics, parameter values, geometry, submesh type, number of submesh points, methods for spatial discretisation and solver for integration (see DFN [script](https://github.com/pybamm-team/PyBaMM/blob/develop/examples/scripts/DFN.py) or [notebook](https://github.com/pybamm-team/PyBaMM/blob/develop/docs/source/examples/notebooks/models/DFN.ipynb)).

For new users we recommend the [Getting Started](https://github.com/pybamm-team/PyBaMM/tree/develop/docs/source/examples/notebooks/getting_started/) guides. These are intended to be very simple step-by-step guides to show the basic functionality of PyBaMM, and can either be downloaded and used locally, or used online through [Google Colab](https://colab.research.google.com/github/pybamm-team/PyBaMM/blob/main/).

Further details can be found in a number of [detailed examples](https://github.com/pybamm-team/PyBaMM/tree/develop/examples), hosted here on
github. In addition, there is a [full API documentation](https://docs.pybamm.org/en/latest/source/api/index.html),
hosted on [Read The Docs](https://readthedocs.org/).
Additional supporting material can be found
[here](https://github.com/pybamm-team/pybamm-supporting-material/).

Note that the examples on the default `develop` branch are tested on the latest `develop` commit. This may sometimes cause errors when running the examples on the pybamm pip package, which is synced to the `main` branch. You can switch to the `main` branch on github to see the version of the examples that is compatible with the latest pip release.

## Versioning

PyBaMM makes releases every four months and we use [CalVer](https://calver.org/), which means that the version number is `YY.MM`. The releases happen, approximately, at the end of January, May and September. There is no difference between releases that increment the year and releases that increment the month; in particular, releases that increment the month may introduce breaking changes. Breaking changes for each release are communicated via the [CHANGELOG](CHANGELOG.md), and come with deprecation warnings or errors that are kept for at least one year (3 releases). If you find a breaking change that is not documented, or think it should be undone, please open an issue on [GitHub](https://github.com/pybamm-team/pybamm).

## 🚀 Installing PyBaMM

PyBaMM is available on GNU/Linux, MacOS and Windows.
We strongly recommend to install PyBaMM within a python virtual environment, in order not to alter any distribution python files.
For instructions on how to create a virtual environment for PyBaMM, see [the documentation](https://docs.pybamm.org/en/latest/source/user_guide/installation/gnu-linux-mac.html#user-install).

### Using pip

[![pypi](https://img.shields.io/pypi/v/pybamm?color=blue)](https://pypi.org/project/pybamm/)
[![downloads](https://img.shields.io/pypi/dm/pybamm?color=blue)](https://pypi.org/project/pybamm/)

```bash
pip install pybamm
```

### Using conda

PyBaMM is available as a conda package through the conda-forge channel.

[![conda_forge](https://img.shields.io/conda/vn/conda-forge/pybamm?color=green)](https://anaconda.org/conda-forge/pybamm)
[![downloads](https://img.shields.io/conda/dn/conda-forge/pybamm?color=green)](https://anaconda.org/conda-forge/pybamm)

```bash
conda install -c conda-forge pybamm
```

### Optional solvers

The following solvers are optionally available:

- [jax](https://jax.readthedocs.io/en/latest/notebooks/quickstart.html)-based solver, see [the documentation](https://docs.pybamm.org/en/latest/source/user_guide/installation/gnu-linux-mac.html#optional-jaxsolver).

## 📖 Citing PyBaMM

If you use PyBaMM in your work, please cite our paper

> Sulzer, V., Marquis, S. G., Timms, R., Robinson, M., & Chapman, S. J. (2021). Python Battery Mathematical Modelling (PyBaMM). _Journal of Open Research Software, 9(1)_.

You can use the BibTeX

```
@article{Sulzer2021,
  title = {{Python Battery Mathematical Modelling (PyBaMM)}},
  author = {Sulzer, Valentin and Marquis, Scott G. and Timms, Robert and Robinson, Martin and Chapman, S. Jon},
  doi = {10.5334/jors.309},
  journal = {Journal of Open Research Software},
  publisher = {Software Sustainability Institute},
  volume = {9},
  number = {1},
  pages = {14},
  year = {2021}
}
```

We would be grateful if you could also cite the relevant papers. These will change depending on what models and solvers you use. To find out which papers you should cite, add the line

```python3
pybamm.print_citations()
```

to the end of your script. This will print BibTeX information to the terminal; passing a filename to `print_citations` will print the BibTeX information to the specified file instead. A list of all citations can also be found in the [citations file](https://github.com/pybamm-team/PyBaMM/blob/develop/pybamm/CITATIONS.bib). In particular, PyBaMM relies heavily on [CasADi](https://web.casadi.org/publications/).
See [CONTRIBUTING.md](https://github.com/pybamm-team/PyBaMM/blob/develop/CONTRIBUTING.md#citations) for information on how to add your own citations when you contribute.

## 🛠 Contributing to PyBaMM

If you'd like to help us develop PyBaMM by adding new methods, writing documentation, or fixing embarrassing bugs, please have a look at these [guidelines](https://github.com/pybamm-team/PyBaMM/blob/develop/CONTRIBUTING.md) first.

## 📫 Get in touch

For any questions, comments, suggestions or bug reports, please see the
[contact page](https://www.pybamm.org/community).

## 📃 License

PyBaMM is fully open source. For more information about its license, see [LICENSE](https://github.com/pybamm-team/PyBaMM/blob/develop/LICENSE.txt).

## ✨ Contributors

This project follows the [all-contributors](https://github.com/all-contributors/all-contributors) specification. Contributions of any kind are welcome!

Click here to see [a full list](https://github.com/pybamm-team/PyBaMM/blob/develop/all_contributors.md) of our contributors' profiles.


# GNPy: Optical Route Planning and DWDM Network Optimization

[![Install via pip](https://img.shields.io/pypi/v/gnpy)](https://pypi.org/project/gnpy/)
[![Python versions](https://img.shields.io/pypi/pyversions/gnpy)](https://pypi.org/project/gnpy/)
[![Documentation status](https://readthedocs.org/projects/gnpy/badge/?version=master)](http://gnpy.readthedocs.io/en/master/?badge=master)
[![GitHub Workflow Status](https://img.shields.io/github/actions/workflow/status/Telecominfraproject/oopt-gnpy/main.yml)](https://github.com/Telecominfraproject/oopt-gnpy/actions/workflows/main.yml)
[![Gerrit](https://img.shields.io/badge/patches-via%20Gerrit-blue)](https://review.gerrithub.io/q/project:Telecominfraproject/oopt-gnpy+is:open)
[![Contributors](https://img.shields.io/github/contributors-anon/Telecominfraproject/oopt-gnpy)](https://github.com/Telecominfraproject/oopt-gnpy/graphs/contributors)
[![Code Coverage via codecov](https://img.shields.io/codecov/c/github/Telecominfraproject/oopt-gnpy)](https://codecov.io/gh/Telecominfraproject/oopt-gnpy)
[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.3458319.svg)](https://doi.org/10.5281/zenodo.3458319)
[![Matrix chat](https://img.shields.io/matrix/oopt-gnpy:matrix.org)](https://matrix.to/#/%23oopt-gnpy%3Amatrix.org?via=matrix.org)

GNPy is an open-source, community-developed library for building route planning and optimization tools in real-world mesh optical networks.
We are a consortium of operators, vendors, and academic researchers sponsored via the [Telecom Infra Project](http://telecominfraproject.com)'s [OOPT/PSE](https://telecominfraproject.com/open-optical-packet-transport) working group.
Together, we are building this tool for rapid development of production-grade route planning tools which is easily extensible to include custom network elements and performant to the scale of real-world mesh optical networks.

![GNPy with an OLS system](docs/images/GNPy-banner.png)

## Quick Start

Install either via [Docker](https://gnpy.readthedocs.io/en/master/install.html#using-prebuilt-docker-images), or as a [Python package](https://gnpy.readthedocs.io/en/master/install.html#using-python-on-your-computer).
Read our [documentation](https://gnpy.readthedocs.io/), learn from the demos, and [get in touch with us](https://github.com/Telecominfraproject/oopt-gnpy/discussions).

This example demonstrates how GNPy can be used to check the expected SNR at the end of the line by varying the channel input power:

![Running a simple simulation example](docs/images/gnpy-transmission-example.svg)

GNPy can do much more, including acting as a Path Computation Engine, tracking bandwidth requests, or advising the SDN controller about a best possible path through a large DWDM network.
Learn more about this [in the documentation](https://gnpy.readthedocs.io/), or give it a [try online at `gnpy.app`](https://gnpy.app/):

[![Path propagation at gnpy.app](docs/images/2022-04-12-gnpy-app.png)](https://gnpy.app/)


# Trafilatura: Discover and Extract Text Data on the Web

[![Python package](https://img.shields.io/pypi/v/trafilatura.svg)](https://pypi.python.org/pypi/trafilatura)
[![Python versions](https://img.shields.io/pypi/pyversions/trafilatura.svg)](https://pypi.python.org/pypi/trafilatura)
[![Documentation Status](https://readthedocs.org/projects/trafilatura/badge/?version=latest)](http://trafilatura.readthedocs.org/en/latest/?badge=latest)
[![Code Coverage](https://img.shields.io/codecov/c/github/adbar/trafilatura.svg)](https://codecov.io/gh/adbar/trafilatura)
[![Downloads](https://static.pepy.tech/badge/trafilatura/month)](https://pepy.tech/project/trafilatura)
[![Reference DOI: 10.18653/v1/2021.acl-demo.15](https://img.shields.io/badge/DOI-10.18653%2Fv1%2F2021.acl--demo.15-blue)](https://aclanthology.org/2021.acl-demo.15/)

## Introduction

Trafilatura is a cutting-edge **Python package and command-line tool**
designed to **gather text on the Web and simplify the process of turning
raw HTML into structured, meaningful data**. It includes all necessary
discovery and text processing components to perform **web crawling,
downloads, scraping, and extraction** of main texts, metadata and
comments. It aims at staying **handy and modular**: no database is
required, the output can be converted to commonly used formats.

Going from HTML bulk to essential parts can alleviate many problems
related to text quality, by **focusing on the actual content**,
**avoiding the noise** caused by recurring elements (headers, footers
etc.), and **making sense of the data** with selected information. The
extractor is designed to be **robust and reasonably fast**, it runs in
production on millions of documents.

The tool's versatility makes it **useful for quantitative and
data-driven approaches**. It is used in the academic domain and beyond
(e.g. in natural language processing, computational social science,
search engine optimization, and information security).

### Features

- Advanced web crawling and text discovery:
   - Support for sitemaps (TXT, XML) and feeds (ATOM, JSON, RSS)
   - Smart crawling and URL management (filtering and deduplication)

- Parallel processing of online and offline input:
   - Live URLs, efficient and polite processing of download queues
   - Previously downloaded HTML files and parsed HTML trees

- Robust and configurable extraction of key elements:
   - Main text (common patterns and generic algorithms like jusText and readability)
   - Metadata (title, author, date, site name, categories and tags)
   - Formatting and structure: paragraphs, titles, lists, quotes, code, line breaks, in-line text formatting
   - Optional elements: comments, links, images, tables

- Multiple output formats:
   - Text
   - Markdown (with formatting)
   - CSV (with metadata)
   - JSON (with metadata)
   - XML or [XML-TEI](https://tei-c.org/) (with metadata, text formatting and page structure)

- Optional add-ons:
   - Language detection on extracted content
   - Graphical user interface (GUI)
   - Speed optimizations

- Actively maintained with support from the open-source community:
   - Regular updates, feature additions, and optimizations
   - Comprehensive documentation

### Evaluation and alternatives

Trafilatura consistently outperforms other open-source libraries in text
extraction benchmarks, showcasing its efficiency and accuracy in
extracting web content. The extractor tries to strike a balance between
limiting noise and including all valid parts.

For more information see the [benchmark section](https://trafilatura.readthedocs.io/en/latest/evaluation.html)
and the [evaluation readme](https://github.com/adbar/trafilatura/blob/master/tests/README.rst)
to run the evaluation with the latest data and packages.

**750 documents, 2236 text & 2250 boilerplate segments (2022-05-18), Python 3.8**

| Python Package | Precision | Recall | Accuracy | F-Score | Diff. |
|----------------|-----------|--------|----------|---------|-------|
| html_text 0.5.2 | 0.529 | **0.958** | 0.554 | 0.682 | 2.2x |
| inscriptis 2.2.0 (html to txt) | 0.534 | **0.959** | 0.563 | 0.686 | 3.5x |
| newspaper3k 0.2.8 | 0.895 | 0.593 | 0.762 | 0.713 | 12x |
| justext 3.0.0 (custom) | 0.865 | 0.650 | 0.775 | 0.742 | 5.2x |
| boilerpy3 1.0.6 (article mode) | 0.814 | 0.744 | 0.787 | 0.777 | 4.1x |
| *baseline (text markup)* | 0.757 | 0.827 | 0.781 | 0.790 | **1x** |
| goose3 3.1.9 | **0.934** | 0.690 | 0.821 | 0.793 | 22x |
| readability-lxml 0.8.1 | 0.891 | 0.729 | 0.820 | 0.801 | 5.8x |
| news-please 1.5.22 | 0.898 | 0.734 | 0.826 | 0.808 | 61x |
| readabilipy 0.2.0 | 0.877 | 0.870 | 0.874 | 0.874 | 248x |
| trafilatura 1.2.2 (standard) | 0.914 | 0.904 | **0.910** | **0.909** | 7.1x |

#### Other evaluations:

- Most efficient open-source library in *ScrapingHub*'s [article extraction benchmark](https://github.com/scrapinghub/article-extraction-benchmark)
- Best overall tool according to [Bien choisir son outil d'extraction de contenu à partir du Web](https://hal.archives-ouvertes.fr/hal-02768510v3/document)
  (Lejeune & Barbaresi 2020)
- Best single tool by ROUGE-LSum Mean F1 Page Scores in [An Empirical Comparison of Web Content Extraction Algorithms](https://webis.de/downloads/publications/papers/bevendorff_2023b.pdf)
  (Bevendorff et al. 2023)

## Usage and documentation

[Getting started with Trafilatura](https://trafilatura.readthedocs.io/en/latest/quickstart.html)
is straightforward. For more information and detailed guides, visit
[Trafilatura's documentation](https://trafilatura.readthedocs.io/):

- [Installation](https://trafilatura.readthedocs.io/en/latest/installation.html)
- Usage:
  [On the command-line](https://trafilatura.readthedocs.io/en/latest/usage-cli.html),
  [With Python](https://trafilatura.readthedocs.io/en/latest/usage-python.html),
  [With R](https://trafilatura.readthedocs.io/en/latest/usage-r.html)
- [Core Python functions](https://trafilatura.readthedocs.io/en/latest/corefunctions.html)
- Interactive Python Notebook: [Trafilatura Overview](docs/Trafilatura_Overview.ipynb)
- [Tutorials and use cases](https://trafilatura.readthedocs.io/en/latest/tutorials.html)

Youtube playlist with video tutorials in several languages:

- [Web scraping tutorials and how-tos](https://www.youtube.com/watch?v=8GkiOM17t0Q&list=PL-pKWbySIRGMgxXQOtGIz1-nbfYLvqrci)

## License

This package is distributed under the [Apache 2.0 license](https://www.apache.org/licenses/LICENSE-2.0.html).

Versions prior to v1.8.0 are under GPLv3+ license.

## Contributing

Contributions of all kinds are welcome. Visit the [Contributing
page](https://github.com/adbar/trafilatura/blob/master/CONTRIBUTING.md)
for more information. Bug reports can be filed on the [dedicated issue
page](https://github.com/adbar/trafilatura/issues).

Many thanks to the
[contributors](https://github.com/adbar/trafilatura/graphs/contributors)
who extended the docs or submitted bug reports, features and bugfixes!

## Context

Developed with practical applications of academic research in mind, this
software is part of a broader effort to derive information from web
documents. Extracting and pre-processing web texts to the exacting
standards of scientific research presents a substantial challenge. This
software package simplifies text data collection and enhances corpus
quality, it is currently used to build [text databases for linguistic
research](https://www.dwds.de/d/k-web).

*Trafilatura* is an Italian word for [wire
drawing](https://en.wikipedia.org/wiki/Wire_drawing) symbolizing the
refinement and conversion process. It is also the way shapes of pasta
are formed.

### Author

Reach out via ia the software repository or the [contact
page](https://adrien.barbaresi.eu/) for inquiries, collaborations, or
feedback. See also X or LinkedIn for the latest updates.

This work started as a PhD project at the crossroads of linguistics and
NLP, this expertise has been instrumental in shaping Trafilatura over
the years. It has first been released under its current form in 2019,
its development is referenced in the following publications:

-   Barbaresi, A. [Trafilatura: A Web Scraping Library and Command-Line
    Tool for Text Discovery and
    Extraction](https://aclanthology.org/2021.acl-demo.15/), Proceedings
    of ACL/IJCNLP 2021: System Demonstrations, 2021, p. 122-131.
-   Barbaresi, A. "[Generic Web Content Extraction with Open-Source
    Software](https://hal.archives-ouvertes.fr/hal-02447264/document)",
    Proceedings of KONVENS 2019, Kaleidoscope Abstracts, 2019.
-   Barbaresi, A. "[Efficient construction of metadata-enhanced web
    corpora](https://hal.archives-ouvertes.fr/hal-01371704v2/document)",
    Proceedings of the [10th Web as Corpus Workshop
    (WAC-X)](https://www.sigwac.org.uk/wiki/WAC-X), 2016.

### Citing Trafilatura

Trafilatura is widely used in the academic domain, chiefly for data
acquisition. Here is how to cite it:

[![Reference DOI: 10.18653/v1/2021.acl-demo.15](https://img.shields.io/badge/DOI-10.18653%2Fv1%2F2021.acl--demo.15-blue)](https://aclanthology.org/2021.acl-demo.15/)
[![Zenodo archive DOI: 10.5281/zenodo.3460969](https://zenodo.org/badge/DOI/10.5281/zenodo.3460969.svg)](https://doi.org/10.5281/zenodo.3460969)

``` shell
@inproceedings{barbaresi-2021-trafilatura,
  title = {{Trafilatura: A Web Scraping Library and Command-Line Tool for Text Discovery and Extraction}},
  author = "Barbaresi, Adrien",
  booktitle = "Proceedings of the Joint Conference of the 59th Annual Meeting of the Association for Computational Linguistics and the 11th International Joint Conference on Natural Language Processing: System Demonstrations",
  pages = "122--131",
  publisher = "Association for Computational Linguistics",
  url = "https://aclanthology.org/2021.acl-demo.15",
  year = 2021,
}
```

### Software ecosystem

Case studies and publications are listed on the [Used By documentation
page](https://trafilatura.readthedocs.io/en/latest/used-by.html).

Jointly developed plugins and additional packages also contribute to the
field of web data extraction and analysis:

Corresponding posts can be found on [Bits of
Language](https://adrien.barbaresi.eu/blog/tag/trafilatura.html). The
blog covers a range of topics from technical how-tos, updates on new
features, to discussions on text mining challenges and solutions.

Impressive, you have reached the end of the page: Thank you for your
interest!


# Elpis (Accelerated Transcription)

[![Build Status](https://travis-ci.org/CoEDL/elpis.svg?branch=master)](https://travis-ci.org/CoEDL/elpis)
[![Coverage Status](https://coveralls.io/repos/github/CoEDL/elpis/badge.svg?branch=master)](https://coveralls.io/github/CoEDL/elpis?branch=master)

Elpis is a tool which allows language workers with minimal computational experience to build their own speech recognition models
to automatically transcribe audio. Elpis provides a way to use multiple speech recognition systems for orthographic or phonemic transcription. The current systems included are [Kaldi](https://kaldi-asr.org) and [Huggingface Transformers wav2vec2](https://huggingface.co/docs/transformers/model_doc/wav2vec2).

## How can I use Elpis?

Documentation is [here](https://elpis.readthedocs.io/).

## I'm An Academic, How Do I Cite This In My Research?

This software is the product of academic research funded by the Australian Research Council
[Centre of Excellence for the Dynamics of Language](http://www.dynamicsoflanguage.edu.au/). If you use the software in
an academic setting, please cite it appropriately as follows:

> Foley, B., Arnold, J., Coto-Solano, R., Durantin, G., Ellison, T. M., van Esch, D., Heath, S., Kratochvíl, F.,
Maxwell-Smith, Z., Nash, D., Olsson, O., Richards, M., San, N., Stoakes, H., Thieberger, N. & Wiles,
J. (2018). Building Speech Recognition Systems for Language Documentation: The CoEDL Endangered
Language Pipeline and Inference System (Elpis). In S. S. Agrawal (Ed.), *The 6th Intl. Workshop on Spoken
Language Technologies for Under-Resourced Languages (SLTU)* (pp. 200–204). Available on https://www.isca-archive.org/sltu_2018/foley18_sltu.pdf.


<!--
Copyright 2023 Ocean Protocol Foundation
SPDX-License-Identifier: Apache-2.0
-->
[![banner](https://raw.githubusercontent.com/oceanprotocol/art/master/github/repo-banner%402x.png)](https://oceanprotocol.com)

[![Aquarius tests](https://github.com/oceanprotocol/aquarius/actions/workflows/pytest.yml/badge.svg)](https://github.com/oceanprotocol/aquarius/actions/workflows/pytest.yml)
[![black](https://github.com/oceanprotocol/aquarius/actions/workflows/black.yml/badge.svg)](https://github.com/oceanprotocol/aquarius/actions/workflows/black.yml)
[![Docker Build Status](https://img.shields.io/docker/cloud/build/oceanprotocol/aquarius.svg)](https://hub.docker.com/r/oceanprotocol/aquarius/)
[![Maintainability](https://api.codeclimate.com/v1/badges/411b97f9749f9dcac801/maintainability)](https://codeclimate.com/github/oceanprotocol/aquarius/maintainability)
[![Test Coverage](https://api.codeclimate.com/v1/badges/411b97f9749f9dcac801/test_coverage)](https://codeclimate.com/github/oceanprotocol/aquarius/test_coverage)
[![PyPI](https://img.shields.io/pypi/v/ocean-aquarius.svg)](https://pypi.org/project/ocean-aquarius/)
[![GitHub contributors](https://img.shields.io/github/contributors/oceanprotocol/aquarius.svg)](https://github.com/oceanprotocol/aquarius/graphs/contributors)

# Aquarius

* [What is Aquarius?](#what-is-aquarius)
   * [How is metadata treated?](#how-is-metadata-treated)
   * [Components and architecture](#components-and-architecture)
      * [The Aquarius API](#the-aquarius-api)
      * [The EventsMonitor](#the-eventsmonitor)
* [Aquarius Setup](#aquarius-setup)
   * [Running Aquarius for multiple chains](#running-aquarius-for-multiple-chains)
* [Using Aquarius](#using-aquarius)
   * [Quickstart](#quickstart)
   * [Learn about Aquarius API](#learn-about-aquarius-api)
   * [Running Aquarius locally](#running-aquarius-locally)
   * [Development](#development)
* [License](#license)

# What is Aquarius?

Aquarius is an off-chain, multi-chain cache for metadata that is published on chain, connected to an Elasticsearch database. Aquarius continually monitors the chains for MetadataCreated and MetadataUpdated events, processes these events and adds them to the database. The Aquarius API offers a convenient way to access the medatata without scanning the chain yourself.

Aquarius is part of the [Ocean Protocol](https://oceanprotocol.com) toolset. 🌊

## How is metadata treated?

The metadata is published on-chain as such:

* Metadata is first (optionally) compressed (using lzma) and (strongly recommended) encrypted, then published on-chain
* The metadata on-chain is not kept in storage, but rather is captured in an event log named `MetadataCreated`
* Aquarius defers to the Provider for encryption and decryption. Aquarius and Provider support utf-8 encoded strings. You can look into the encrypt/decrypt flows if you want to learn more, but you will generally not need to go in-depth just to use Aquarius.

For more details on working with OCEAN DIDs check out the [DID concept documentation](https://docs.oceanprotocol.com/core-concepts/did-ddo/).
The [DDO Metadata documentation](https://docs.oceanprotocol.com/core-concepts/did-ddo#metadata) goes into more depth regarding metadata structure.

## Components and architecture

Aquarius is a simple, lightweight scanner and API. It is built using Python, using the Flask framework.

### The Aquarius API

Aquarius provides REST api to fetch the data from off-chain datastore.
Please refer to [API.md](API.md) file for details on the API itself.

### The EventsMonitor

The events monitor runs continuously to retrieve and index the chain Metadata. It saves the results into an Elasticseach database. The monitor reads the events `data` argument, decompresses the metadata json object, then runs schema validation before saving it to the database. The monitor is highly customisable, and it consists of the following components:

- an ElasticsearchInstance, configured through env variables
- an associated MetadataContract, configured through the `METADATA_CONTRACT_ADDRESS` env variable
- a Decryptor class that handles decompression and decryption on the chain data, through communication with Provider
- a set of `ALLOWED_PUBLISHERS`, if such a restriction exists. You can set a limited number of allowed publisher addresses using this env variable.
- a Purgatory, based on the `ASSET_PURGATORY_URL` and `ACCOUNT_PURGATORY_URL` env variables. These mark some assets as being in purgatory (`"isInPurgatory": True`), enabling restrictions for some assets or accounts.
- a VeAllocate, based on the `VEALLOCATE_URL` and `VEALLOCATE_UPDATE_INTERVAL` env variables. This updates the veAllocation for datasets.
- start blocks, if such defined using `BFACTORY_BLOCK` and `METADATA_CONTRACT_BLOCK`. These start blocks are coroborated with the last stored blocks per Elasticsearch, to avoid indexing multiple times

The EventsMonitor processes block chunks as defined using `BLOCKS_CHUNK_SIZE`. For each block, it retrieves all `MetadataCreated` and `MetadataUpdated` events, and these events are processed inside the `MetadataCreatedProcessor` and `MetadataUpdatedProcessor` classes. These processors run the following flow:

- optionally check permissions with the `RBAC_SERVER_URL` and `ALLOWED_PUBLISHERS`
- decompresses and optionally decrypts the asset metadata
- checks whether the asset needs to be sent to purgatory
- creates the JSON record and saves it in Elasticsearch
- if a `MetadataUpdated` event is detected on an asset that does not exist in Elasticsearch already, then it is treated as a `MetadataCreated` event.

# Aquarius Setup
The following environment variables are required for running Aquarius:

```
# URL of ethereum network.
# Recommendation: when connecting to an official network, create an Infura project id and set this
# to use the Infura url including the project id
EVENTS_RPC
  examples:
  "http://172.15.0.3:8545", "wss://rinkeby.infura.io/ws/v3/INFURA_ID"

# Use this to run the EventsMonitor in a thread from the main Flask app
EVENTS_ALLOW
  accepted values:
    "0" to disable
    "1" to enable

# Run the EventsMonitor in a separate process, overrides `EVENTS_ALLOW`.
# This is only used when running in `docker` container
RUN_EVENTS_MONITOR
  accepted values:
    "0" to disable
    "1" to enable

# Start a HTTP server inside the events monitor. This is useful for K8 live probing. You must simply access the root endpoint on port 5001. IE: http://172.0.0.1:5001 which will respond with 200 OK if the events thread is up.  Otherwise, there will be no response
EVENTS_HTTP
  accepted values:
    "1" to enable
```
And these are optional
```bash
# Enables the Aquarius API. Default: 1, disable if you only want to use the events monitor, without exposing an API.
RUN_AQUARIUS_SERVER

# Identify instance of Aquarius to Provider, when decrypting assets. Provider may allow or deny decryption based on this address.
PRIVATE_KEY

# Path to the `address.json` file or any json file that has the deployed contracts addresses
ADDRESS_FILE

# Specify the network name to use for reading the contracts addresses from the `ADDRESS_FILE`.
# If not set, the network name is derived from current network id or from the `EVENTS_RPC` value, by splitting out the wss://, http:// or https:// part and the suffixes
NETWORK_NAME

# Restrict metadata caching to publishers in this list. It is a list of publisher addresses.
ALLOWED_PUBLISHERS

# Metadata contract address. Use it if you want to overwrite values from ocean-contracts
METADATA_CONTRACT_ADDRESS

# The block number of `Metadata` contract deployment
METADATA_CONTRACT_BLOCK

# if set to 1, read events from the first Metadata and BFactory block number, or a specific block number (used for debugging)
IGNORE_LAST_BLOCK

# When scanning for events, limit the chunk size. Infura accepts 10k blocks, but others will take only 1000 (default value)
BLOCKS_CHUNK_SIZE

# URLs of asset purgatory and account purgatory. If neither exists, the purgatory will not be processed. The list should be formatted as a list of dictionaries containing the address and reason. See https://github.com/oceanprotocol/list-purgatory/blob/main/list-accounts.json for an example
# IMPORTANT.  If you are running multiple aquarius event monitors (for multiple chains), make sure that only one event-monitor will handle purgatory
ASSET_PURGATORY_URL
ACCOUNT_PURGATORY_URL

# Customise purgatory update (refresh) time (in number of minutes)
PURGATORY_UPDATE_INTERVAL

# URL for getting the veAllocation list. If not exists, the veAllocate will not be processed. Possible values are: https://df-sql.oceandao.org/nftinfo for mainnet and https://test-df-sql.oceandao.org/nftinfo for goerli, because veOCEAN is deployed only on this networks. All other networks SHOULD NOT HAVE this defined.  The list should be formatted as a list of dictionaries containing chainID,nft_addr and ve_allocated
VEALLOCATE_URL

# Customise veAllocate update (refresh) time (in number of minutes)
VEALLOCATE_UPDATE_INTERVAL

# The URL of the RBAC Permissions Server. If set, Aquarius will check permissions with RBAC. Leave empty/unset to skip RBAC permission checks.
RBAC_SERVER_URL

# Whether to start clean and reindex events on chain id
EVENTS_CLEAN_START

# Subgraph URLs in the form of a json-dumped string mapping chain_ids to subgraph urls.
SUBGRAPH_URLS

# Process a queue with failed assets, e.g. retry where temporary network flukes or similar conditions caused a failure
PROCESS_RETRY_QUEUE

# For how long to retry such an event, before giving up. Defaults to 2 weeks
PROCESS_RETRY_MAX_HOLD

# Customize sleep time for events monitor between checking for new events. Defaults to 30 seconds
EVENTS_MONITOR_SLEEP_TIME
# Customize sleep time for events monitor between queue processing. Defaults to 60 seconds
EVENTS_PROCESS_QUEUE_SLEEP_TIME
# Customize sleep time for events monitor between updating ve_allocate. Defaults to 300 seconds
EVENTS_VE_ALLOCATE_SLEEP_TIME
# Customize sleep time for events monitor between checking for nft transfers. Defaults to 300 seconds
EVENTS_NFT_TRANSFER_SLEEP_TIME
# Customize sleep time for events monitor between checking for purgatory lists. Defaults to 300 seconds
EVENTS_PURGATORY_SLEEP_TIME
```
## Running Aquarius for multiple chains

If you want to index multiple chains using a single Aquarius instance, that is possible. The OCEAN version of Aquarius uses this exact flow. To enable multi-chain indexing, these are the necessary steps:
 * Run one or more pods, with `RUN_AQUARIUS_SERVER=1` , `RUN_EVENTS_MONITOR=0` and `EVENTS_ALLOW=0`.  This basically enables only the API part of Aquarius.
 * For each chain, start a pod with the following env variables:
     * Set `RUN_EVENTS_MONITOR=1` and `RUN_AQUARIUS_SERVER=0` (run only the EventsMonitor part of Aquarius)
     * Set coresponding `EVENTS_RPC`, `NETWORK_NAME`, `BLOCKS_CHUNK_SIZE`, `METADATA_CONTRACT_BLOCK`, `METADATA_CONTRACT_ADDRESS` etc.

A list of deployment values and schematics [can be found here](https://github.com/oceanprotocol/aquarius/tree/main/deployment)

Voilà! You are now running a multi-chain Aquarius.

# Using Aquarius

## Quickstart

If you're developing a marketplace, you'll want to run Aquarius and several other components locally. The easiest way to do that is to use Barge. See the instructions in [the Barge repository](https://github.com/oceanprotocol/barge).

## Learn about Aquarius API

[Here](https://docs.oceanprotocol.com/api-references/aquarius-rest-api) is API documentation. You can find more details about the ontology of the metadata in the [Ocean documentation](https://docs.oceanprotocol.com/core-concepts/did-ddo#metadata).

If you have Aquarius running locally, you can find a Swagger API documentation at [http://localhost:5000/api/docs](http://localhost:5000/api/docs) or maybe [http://0.0.0.0:5000/api/docs](http://0.0.0.0:5000/api/docs).

- Tip 1: If that doesn't work, then try `https`.
- Tip 2: If your browser shows the Swagger header across the top but says "Failed to load spec." then we found that, in Chrome, if we went to `chrome://flags/#allow-insecure-localhost` and toggled it to Enabled, then relaunched Chrome, it worked.

## Running Aquarius locally

For testing purposes, running Aquarius from [barge](https://github.com/oceanprotocol/barge/) should suffice, but if you want to run your own version of Aquarius (with any configurations or alterations), you can do that by following the instructions in [the developers documentation](developers.md).

## Development

If you want to improve or customise Aquarius, you're our favourite kind of person! Go to [the developers flow](developers.md) to learn more about how you can contribute.

# License

Copyright 2022 Ocean Protocol Foundation Ltd.

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.


.. |PyPI| image:: https://img.shields.io/pypi/v/pypeit?label=PyPI&logo=pypi&logoColor=white
    :target: https://pypi.org/project/pypeit/#history

.. |pypi_downloads| image:: https://img.shields.io/pypi/dm/pypeit
    :target: https://pypi.org/project/pypeit/#files

.. |License| image:: https://img.shields.io/github/license/pypeit/PypeIt
   :target: https://github.com/pypeit/PypeIt/blob/release/LICENSE.rst

.. |CITests| image:: https://github.com/pypeit/PypeIt/workflows/CI%20Tests/badge.svg
    :target: https://github.com/pypeit/PypeIt/actions?query=workflow%3A"CI+Tests"

.. |Coverage| image:: https://codecov.io/gh/PypeIt/pypeit/branch/release/graph/badge.svg
    :target: https://codecov.io/gh/PypeIt/pypeit

.. |docs| image:: https://readthedocs.org/projects/pypeit/badge/?version=latest
    :target: https://pypeit.readthedocs.io/en/latest/

.. |DOI_latest| image:: https://zenodo.org/badge/DOI/10.5281/zenodo.3743493.svg
   :target: https://doi.org/10.5281/zenodo.3743493

.. |JOSS| image:: https://joss.theoj.org/papers/10.21105/joss.02308/status.svg
   :target: https://doi.org/10.21105/joss.02308

.. |arxiv| image:: https://img.shields.io/badge/arxiv-2005.06505-black
   :target: https://arxiv.org/abs/2005.06505

.. |astropy| image:: http://img.shields.io/badge/powered%20by-AstroPy-orange.svg?style=flat
    :target: http://www.astropy.org/

.. |forks| image:: https://img.shields.io/github/forks/pypeit/PypeIt?style=social
   :target: https://github.com/pypeit/PypeIt

.. |stars| image:: https://img.shields.io/github/stars/pypeit/PypeIt?style=social
   :target: https://github.com/pypeit/PypeIt

.. |github| image:: https://img.shields.io/badge/GitHub-PypeIt-brightgreen
   :target: https://github.com/pypeit/PypeIt

.. image:: https://raw.githubusercontent.com/pypeit/PypeIt/release/doc/_static/PypeIt_color_white_txt_black_background.png
    :target: https://github.com/pypeit/PypeIt
    :width: 485

PypeIt |forks| |stars|
======================

|github| |pypi| |pypi_downloads| |License|

|docs| |CITests| |Coverage|

|DOI_latest| |JOSS| |arxiv|

PypeIt is a Python package for semi-automated reduction of astronomical
spectroscopic data. Its algorithms build on decades-long development of previous
data reduction pipelines by the developers. The reduction procedure - including
a complete list of the input parameters and available functionality - is
provided by our `online documentation
<https://pypeit.readthedocs.io/en/release/>`__.

PypeIt is designed to be used by both advanced spectroscopists with prior data
reduction expertise and astronomers with no prior experience of data reduction.
It is highly configurable and designed to be applied to any standard
slit-imaging spectrograph, including long-slit, multi-slit, as well as
cross-dispersed echelle spectra.  **The spectrographs that PypeIt can be used
with are listed** `here
<https://pypeit.readthedocs.io/en/release/spectrographs/spectrographs.html>`__.

Also note that `this link
<https://pypeit.readthedocs.io/en/release/spectrographs/spectrographs.html#instrument-specific-details>`__
contains some useful information about reducing data
with certain instruments that you might also find helpful.

In addition to our primary code base, we maintain an extensive `development
suite <https://github.com/pypeit/PypeIt-development-suite>`__ primarily used to
perform multiple layers of code testing, from basic unit tests to full
end-to-end tests of all our command-line scripts.  **If you are new to PypeIt,
you are encouraged to pull example data from the DevSuite for your instrument
when learning how to use the software.**

----

.. _community:

Community
+++++++++

As a project, PypeIt is committed to fostering a welcoming, diverse, and
inclusive community.  As a member of this community you are expected to read and
follow our `Code of Conduct
<https://pypeit.readthedocs.io/en/release/codeconduct.html>`__.

Along with our extensive `online documentation
<https://pypeit.readthedocs.io/en/release/>`__, we encourage the PypeIt user
base to communicate via our `PypeIt Users Slack <https://pypeit-users.slack.com>`__.
All are welcome to join using `this invitation link <https://join.slack.com/t/pypeit-users/shared_invite/zt-1kc4rxhsj-vKU1JnUA~8PZE~tPlu~aTg>`__.

If you find a bug (particularly one that is experienced by others in the Users
Slack) or have a feature request, please `submit an issue
<https://github.com/pypeit/PypeIt/issues>`__.

----

Citation
++++++++

If you use PypeIt in your research, please cite the following publications
(we provide the relevant `BibTeX entries
<https://pypeit.readthedocs.io/en/release/index.html#pypeit-bibtex-entries>`__
for your convenience):

 - Prochaska et al. (2020, JOSS): `arXiv <https://ui.adsabs.harvard.edu/abs/2020arXiv200506505P/abstract>`__, `JOSS <https://joss.theoj.org/papers/10.21105/joss.02308>`__
 - Prochaska et al. (2020, Zenodo): `Zenodo <https://ui.adsabs.harvard.edu/abs/2020zndo...3743493P/abstract>`__

If there is no place to include the relevant citations in the text of
the publication, please include the following acknowledgement
(provided in latex and using the provided `BibTeX entries
<https://pypeit.readthedocs.io/en/release/index.html#pypeit-bibtex-entries>`__):

.. code-block:: latex

    This research made use of \ttfamily{PypeIt},\footnote{\url{https://pypeit.readthedocs.io/en/latest/}}
    a Python package for semi-automated reduction of astronomical slit-based spectroscopy
    \citep{pypeit:joss_pub, pypeit:zenodo}.

----

Funding
+++++++

PypeIt receives direct funding from the following sources:

  * NASA ADAP (A20-0412, 20-1018)
  * W.M. Keck Observatory
  * University of California Observatories

We also rely on important in-kind contributions from individuals at
Caltech, the Multiple Mirror Observatory, and elsewhere.

----

Developers
++++++++++

PypeIt is an open-source, community developed package.  Astronomers are
encouraged to join the project and should review our `Code of Conduct
<https://pypeit.readthedocs.io/en/release/codeconduct.html>`__ and `Development
Guidelines <https://pypeit.readthedocs.io/en/release/dev/development.html>`__.
We would also appreciate if you contact the lead developers (JXP, JFH) before
beginning development activities.

The following persons have contributed substantially to the
development of PypeIt.

* J Xavier Prochaska (JXP)
* Joseph F. Hennawi (JFH)
* Kyle B. Westfall
* Ryan J. Cooke
* Feige Wang
* Tiffany Hsyu
* Frederick B. Davies
* Emanuele Paolo Farina
* Debora Pelliccia
* James Reichwein
* Milan Roberson
* Timothy Pickering
* Timothy Ellsworth-Bowers
* Gregory Simonian
* Heather Martin


---

**Documentation**: https://django-codemod.readthedocs.io

**Source Code**: https://github.com/browniebroke/django-codemod

---

A tool to help upgrade Django projects to newer version of the framework by automatically fixing deprecations.

## The problem

When maintaining a Django site, over time you'll find yourself to a point where you'll need to update to the next major version of Django. When Django APIs changes, functions move or are removed, changing usages in your project might add up to many changes. Often these changes are simple to do, but sometimes a simple "find and replace" is not possible.

Take, for instance, the removal of the `url()` function from Django 4.0, to be replaced by `re_path()`. In simple cases, you might even want to switch to `path()`, which has a nicer API. A typical Django project easily has 100's or routes, so this simple decision becomes a much longer task when to be made for each of them.

### This solution

This project solves this problem by providing codemodders for simple changes like this. A codemodder re-writes your code from the old way to the new way.

With the help of AST analysis, we're able to understand what modifications are applicable, remove imports as they become irrelevant, and add missing ones as they are needed.

To continue the example, the tool will look at the route in the `url()` call, and decide whether the regular expression may be replaced by one of the built-in URL converters and use `path()` or stick to a regex and use `re_path()`.

Interested? Check out [the documentation](https://django-codemod.readthedocs.io) for usage and the full list of codemodders.

### What this tool is not

- This tool is best suited for Django sites, NOT for reusable Django applications. The project needs to target a single Django version, e.g. 3.1.x.
- You do NOT need to install this tool as part of your project dependencies, it is a CLI tool, not a Django package to be installed in your site.

### Similar tools

[django-upgrade](https://github.com/adamchainz/django-upgrade) is a similar tool written by Adam Johnson. It's a reimplementation taking a different approach based only on standard library module.

django-codemod is based on [libCST](https://libcst.readthedocs.io/) (Concrete Syntax Tree) which is a limiting factor in terms of speed. By using standard library modules, django-upgrade is a lot faster and is able to support the latest Python, however it requires Python 3.8+.

## Contributors ✨

Thanks goes to these wonderful people ([emoji key](https://allcontributors.org/docs/en/emoji-key)):

Bruno Alla
💻 📖 🤔

Aarni Koskela
💻 🤔 ⚠

Adam Johnson
📖

Nikita Sobolev
📖

Chris VanderKolk
💻

John Vandenberg
🐛 💻

Anjishnu
🚇

Drew Winstel
🤔

Dmytro Litvinov
📖

M. Zulqarnain
📖

This project follows the [all-contributors](https://github.com/all-contributors/all-contributors) specification. Contributions of any kind welcome!

## Credits

This package was created with
[Cookiecutter](https://github.com/audreyr/cookiecutter) and the
[audreyr/cookiecutter-pypackage](https://github.com/audreyr/cookiecutter-pypackage)
project template.