目录
- .githubExpose readPixels, prepare for offscreen render.2年前
- ExamplesUpdate how we get underlying tuple pointer2年前
- SourcesUpdate API to 2.3.02年前
- TestsChange minimum ios unit test version to 13.02年前
- bazelUpdate with basic mujoco setup.3年前
- externalShould be header only3年前
- scriptsUpdate vscode/build.sh3年前
- .bazelrcUpdate to latest MuJoCo.3年前
- .gitignoreAdd .bazelrc into the repo.3年前
- .spi.ymlList documentation targets for ios.2年前
- .swift-format.jsonModify swift-format script.3年前
- BUILD.bazelConditionally include GLContext.swift3年前
- LICENSEUpdate with basic mujoco setup.3年前
- Package.resolvedUpdate API to 2.3.02年前
- Package.swiftUpdate API to 2.3.02年前
- README.mdUpdate README.md2年前
- WORKSPACEUpdate API to 2.3.02年前
- deps.bzlUpdate deps.bzl.2年前
邀请码
MuJoCo for Swift
This is a Swift binding for MuJoCo physics simulation library.
MuJoCo is a very accurate CPU-based physics simulation library. Since its acquisition by DeepMind, MuJoCo has been more readily available broadly.
MuJoCo is at the heart of physics simulation in the realm of deep reinforcement learning. In OpenAI Gym, there are many diverse environments simulated with MuJoCo.
Up until now, I only dipped a bit into DRL with https://github.com/liuliu/s4nnc/tree/main/examples. OpenAI Gym is OK for these simple mechanisms and I don’t mind to wait a few minutes more. But most recently, I grown interests in more serious use of DRL / PPO under Sim2Real banner. For these, it is popular to either use Isaac Gym or exploiting multi-core for environment runs. For later, doing it with
multiprocesspackage of Python is awkward but the preferred way.If we can run MuJoCo from Swift, we can avoid the trip into Python entirely and simply use
DispatchQueue.concurrentPerformfor environment runs.Installation
MuJoCo for Swift can be installed through either Swift Package Manager or Bazel.
Install with Swift Package Manager
You can add MuJoCo for Swift in your project from here:
Install with Bazel
You can simply add MuJoCo for Swift as a dependency in
WORKSPACE:MuJoCo for Swift should work on macOS, Linux and iOS. The
GLContextis only available on macOS and Linux.Automatic Interface Generation
Struct
A mixed strategy was used for MuJoCo interface generation. MuJoCo’s API heavily leans towards exposed public C structs. MuJoCo for Swift has to expose these C structs. Wrappers for these C structs are manually created with following principles:
typealiasto its C struct;public structwith C struct interior, keeping the memory layout exactly the same (can better expose certain properties, more on that later);mj_deleteXXXmethods. These arepublic structwith afinal class Storageinterior to track lifetime.Which out of the three implemented was tracked in
Sources/codegen/functionExtension.swift. We later generatedSources/MjObject+Extensions.swiftto encode above strategies into Swift protocol. AllMjStructconforms to this protocol which provides associated type of the underlying C struct, as well as the memory access methodwithCTypeUnsafeMutablePointer(to:).MuJoCo’s C headers are parsed and used to generate properties on structs and functions on structs. These are
XX+Extensions.swiftandXX+Functions.swiftfiles. All accessors are generated for public C structs from MuJoCo.They can be reproduced with:
Extra care was taken to make sure comments are properly parsed and added to these extensions. https://liuliu.github.io/swift-mujoco is the documentation generated based on these comments.
MjArray<T>is the array type that exposes static or dynamic arrays within a C struct. It retains the underlying storage to make sure the access is safe. It also conforms to set of protocols such that forinoutparameters and other array parameters, you can either pass vanilla array orMjArray<T>(orMjTuple, through .tuple()) and expect it just works.Enum
enumare parsed and generated inMjt.swiftfile. Because there is no type annotation, we do our best to infer which int type are enums from comment.MjtEnableBit,MjtDisableBit,MjtCatBitandMjtPertBitare special handled to beOptionSet.Functions
C functions are not scoped to a particular object. We have to infer these. First, we try to infer which group of APIs it belongs to with the prefix:
mj_matchesmjXXstructs,mjv_matchesmjvXXstructs. We prefer the first parameter, otherwise the last parameter (as it is often used as write to). If no suitable object to be found, it is a free function.The interface generation process also treats
constannotation seriously. Withoutconst, these methods are annotated withmutating. If the parameter is a pointer withoutconst, it is annotated withinout.Not all functions are automatically generated, some of these are manually implemented because:
mj_loadXMLcan be better translated withthrowsfor errors;MjUI
Whenever possible, we lean towards automatic interface generation. That’s why we kept certain APIs in a way that look weird.
MjUIhas many quirks that at odds with this philosophy. In particular,MjuiDefautomatically associated the UI control with the underlying storagepdata. Becausepdatais a pointer, it has no regards to the underlying storage lifetime. A set of property wrappers:MjuiDefState,MjuiDefStateMapare introduced to solve this issue. Although users are still responsible to make sure the underlying storage lifetime longer thanMjUIitself, you don’t need to deal with rawpdata. AMjuiDefObjectMapperis introduced to facilitate direct mapping between anMjStructand aMjuiDef. You need to pay extra attention because there is no guarantee on underlyingMjStructlifetime withMjuiDefObjectMapper. A recommended way is to group them both under afinal classto make sure their lifetime is in sync.Constants
Only constants related to
MjUIare ported over so far.Callbacks
Callbacks can be found under
Mjcb. These are manually ported callbacks but does support Swift closures (i.e. captures).Reflection
CustomReflectableprotocol conformance is implemented for MjStruct. These should contain all the fields in C structs with very few exceptions (bufferandstackinMjData,bufferinMjModelanduserdatainMjUI).String
MuJoCo leans heavily on static allocated strings. To make interaction easier, these are exposed as ordinary Swift strings. The back-and-forth copying can be expensive. Because static allocated strings have hard limit, there is a silent truncation if such limit reached.
GLContext
A
GLContextobject is introduced to delegate GLFW interactions. Functionalities fromuitools.ccin./sample/of MuJoCo were added to make interactions withMjUIeasier. This object is a bit overreaching as it provides access to clipboard, timing and drag & drop functions.Examples
Both
Examples/simulateandExamples/antshould provide good starting points to learn about the APIs. To run:Visit documentation at: https://liuliu.github.io/swift-mujoco. These should be kept up-to-date with
mainbranch.Appendix
List of Supported MuJoCo C APIs