feat: add cyclic peptide support to relative position encoding

[ioannisa92]

Summary

• Adds cyclic: bool = False field to the Chain inference query model so individual chains can be flagged as cyclic peptides
• Propagates the cyclic flag through featurization: is_cyclic annotation on atom arrays → cyclic_mask boolean tensor in the feature dict
• Implements cyclic_offset() in relpos.py to compute a topologically-aware pairwise offset matrix for cyclic chains (wraps distances past the midpoint back toward zero)
• Integrates cyclic offset into relpos_complex(): for any chain where cyclic_mask is set, the standard linear offset is replaced with the cyclic offset for intra-chain pairs
• Adds an example cyclic multimer inference input (query_multimer_cyclic.json) with MDM2 + a cyclic peptide binder (chain B)

[jandom]

@ioannisa92 this is terrific, please let us know if you want to polish this up a bit (it's in draft probably for a reason) or do you want us to jump on this?

[ioannisa92]

@jandom i will make it a PR today probably. I just want the tests to run with the cyclic offset.

Who should i request as reviewer?

Additionally, when i did this analysis in the other repo #526 the effect of the cyclic offset was greater. Is there an explanation why OF3 has a different behavior?

[jnwei]

This is great work @ioannisa92 !

I verified that I can run the provided multimer_cyclic example using the OpenFold3 preview 2 weights.

I have a few nits regarding code style / test example organization. But overall this is really good.

[jandom]

Who should i request as reviewer?

@ioannisa92 good stuff, you should just tag me and Jennifer for now – we can pull more folks if needed

Additionally, when i did this analysis in the other repo aqlaboratory/openfold#526 the effect of the cyclic offset was greater. Is there an explanation why OF3 has a different behavior?

Ha, there could be any number of explanations :D

[ioannisa92]

@jnwei @jandom Apart from moving the test is there anything else blocking merge? This feels like something that is beyond the scope of this PR

[jandom]

Ah, sorry – I tagged myself in for review, I need a bit of time to go through this. By the end of the week, so today tomorrow.

[jandom]

Okay, immediate comment is we need to make linting and tests pass (easy) and i want to see thumbs up from @jnwei (so just re-request review from her)

[jnwei]

Overall this looks good!

Just one last thing from me - It looks like the linter is catching some errors. Could you use the dev environment and do a ruff check on the codebase? The contributor's guide has some quick instructions for how to install and use ruff

[ioannisa92]

@jandom I ran ruff and all checks pass

[jandom]

@ioannisa92 thanks – i've kicked off tests to see if everything passes

[jandom]

@ioannisa92 I think we've got some test failures, if you have a moment to fix those and then I think this is good to go

[ioannisa92]

@jandom i had to redo the test data under /openfold-3/openfold3/tests/test_data/structure_from_query per your README. The tests pass now locally

[ioannisa92]

@jandom The tests that still fail test_triangular_attention.py and test_triangular_multiplicative_update.py dont seem to have anything to do with the cyclic offset. I have used --force-regen on those and they still fail locally.

[jandom]

@ioannisa92 brilliant stuff, will re-run now

[jandom]

@ioannisa92 one last thing we can't merge ATM because of conflicts, we also can't resolve the conflicts ourselves (because we can't push to your forked repo). Would you have a moment to look into it?

[jandom]

A bunch of test failures

FAILED openfold3/tests/core/data/primitives/structure/test_query.py::test_consistent_structure_from_smiles_and_ccd_code[c1ccc(c(c1)CCCl)NC(=O)Nc2cc(ccc2n3ccnc3)C(F)(F)F-A1ASQ] - AttributeError: 'list' object has no attribute 'array_length'

All these will go away once you update this branch @ioannisa92 (ie merge main into it)

[ioannisa92]

@jandom ok merged and tests now pass

[jandom]

This is awesome thank you so much. I think we’re ready to go, will give it a final look tomorrow Many thanks, great contribution!!

…

On Tue, Jul 7, 2026 at 20:03 Ioannis Anastopoulos ***@***.***> wrote: *ioannisa92* left a comment (aqlaboratory/openfold-3#281) <#281 (comment)> @jandom <https://github.com/jandom> ok merged and tests now pass — Reply to this email directly, view it on GitHub <#281?email_source=notifications&email_token=AADAVG7H4QIRXCYNRDAJHG35DU3NZA5CNFSNUABFM5UWIORPF5TWS5BNNB2WEL2JONZXKZKDN5WW2ZLOOQXTIOJQGY4TONBQGI32M4TFMFZW63VHNVSW45DJN5XKKZLWMVXHJLDGN5XXIZLSL5RWY2LDNM#issuecomment-4906974027>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AADAVGZBB4EXH44MPKD5G335DU3NZAVCNFSNUABGKJSXA33TNF2G64TZHMYTAOBQGQ2DQMBSGI5US43TOVSTWNBXGU2DCNBUGY4DHILWAI> . You are receiving this because you were mentioned.Message ID: ***@***.***>

[jandom]

I'm getting errors running training after the merge, will revert and then we can fix and merge again

  File "/home/jandom/workspace/openfold-3/openfold3/core/data/pipelines/featurization/structure.py", line 239, in featurize_target_gt_structure_of3
    features_target = featurize_structure_of3(
        atom_array=atom_array,
        n_tokens=n_tokens,
        is_gt=False,
    )
  File "/home/jandom/workspace/openfold-3/openfold3/core/data/pipelines/featurization/structure.py", line 195, in featurize_structure_of3
    atom_array.is_cyclic[token_starts], dtype=torch.bool
    ^^^^^^^^^^^^^^^^^^^^
  File "/home/jandom/workspace/openfold-3/.pixi/envs/openfold3-cuda12/lib/python3.14/site-packages/biotite/structure/atoms.py", line 346, in __getattr__
    raise AttributeError(
        f"'{type(self).__name__}' object has no attribute '{attr}'"
    )
AttributeError: 'AtomArray' object has no attribute 'is_cyclic'